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1  Introduction 


This  document  presents  recommendations  for  commands  and  interface  mech¬ 
anisms  used  in  level-III  interactive  video  (IV)  systems.  The  recommendations 
are  based  on  functional  definitions  that  were  developed  with  input  from  IV 
manufacturers,  developers  and  users.  The  foundation  for  these  definitions  in¬ 
cludes  an  extensive  set  of  models  that  were  developed  for  internal  use  to  en¬ 
sure  an  approach  that  addresses  current  needs  and  capabilities  while 
providing  for  future  growth  in  IV  technology. 


This  is  a  working  document.  As  such,  it  serves  two  major  purposes.  First, 
manufacturers  and  developers  can  start  working  to  implement  the  recommen¬ 
dations  now  instead  of  waiting  for  the  completion  of  the  formal  ratification 
process.  Second,  industry  members  and  end-users  can  contribute  to  the  final 
recommendations  by  submitting  comments. 


1 .1  Scope  of  the  recommended  practices 


The  recommended  practices  in  this  document  provide  platform  independence 
but  not  device  interoperability  (plug-and-play).1  Platform  independence  lets 
applications  run  without  modification  on  any  hardware  platform  based  on  the 
same  general  class  of  host  computers.  It  requires  consistent  behavior  from  dif¬ 
ferent  hardware  platforms  at  the  application-interface  level. 

Furnishing  such  consistency  is  the  immediate  goal  of  the  software  definitions 
in  this  working  document  This  goal  is  not  trivial.  We  anticipate  changes  in 
this  document  as  specific  needs  are  uncovered  during  the  implementation  of 
the  recommendations.  However,  we  anticipate  that  these  changes  will  be  un¬ 
covered  early  in  the  implementation  process  and  will  not  be  extensive  enough 
to  significantly  impact  implementations  based  on  this  document. 


1.  Device  interoperability  requires  classes  of  related  devices  to  furnish  functionally  identical  services  at  the 
component  level.  This  document  does  not  address  device  interoperability. 
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Recommended  Practices  for  Interactive  Video  Portability 


The  current  recommendations  address  MS-DOS  and  PC  DOS  systems  based 
on  Intel  80x86  processor  architecture.  Other  operating  systems  and  architec¬ 
tures  will  be  addressed  in  the  future. 


1 .2  Goals  and  benefits 


IV  technology  fulfills  many  types  of  training  and  educational  requirements, 
yet  platform-specific  courseware  has  severely  restricted  its  use.  Many  applica¬ 
tions  require  proprietary  software,  special  hardware,  or  both.  We  recognize 
the  critical  need  for  compatibility  in  IV  technology  to  promote  IV  usage;  lower 
costs  for  integrators,  developers,  and  users;  and  encourage  integration  in  a 
competitive  market. 


The  specific  goal  of  the  current  recommendations  is  to  establish  a  uniform  ap¬ 
plication  interface  and  command  set  that  supports  unmodified  IV  application 
programs  on  different  delivery  systems.  We  do  not  endorse  specific  IV  hard¬ 
ware  systems  or  mandate  the  use  of  products  from  specific  suppliers.  Instead, 
our  ultimate  mission  is  to  end  such  requirements. 


Adoption  of  the  current  recommendations  will  benefit  the  IV  industry  by  fur¬ 
nishing  a  common  ground  for  manufacturers,  systems  integrators, 
courseware  developers,  and  end-users  in  a  field  of  rapidly  changing  technolo¬ 
gies.  The  recommendations  will  furnish  many  benefits  including: 


•  Broader  acceptance  of  IV  technology  and  subsequent  growth  of  the  mar¬ 
ketplace. 

•  Assurance  of  long-lasting  investments  in  IV  applications  and  systems. 

•  Reduced  need  to  change  and  support  IV  applications  for  specific  hard¬ 
ware  configurations. 

•  Increased  productivity,  lower  maintenance  costs,  and  improved  applica¬ 
tion  consistency  across  platforms. 

•  Higher  quality  and  less  costly  IV  applications  resulting  from  a  larger 
marketplace  and  the  application  of  resources  to  software  development 
instead  of  customizing  software  and  platforms. 

•  Greater  compatibility  between  international  IV  communities. 
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1 .3  Document  organization  and  intended  audience 


The  information  in  this  document  is  intended  for  IV  manufacturers,  systems 
integrators,  authoring  system  developers,  and  software  developers  who  wish 
to  comply  with  the  recommended  practices.  This  document  includes  nine 
major  sections  and  four  appendices. 

•  Section  1,  this  section,  includes  background  information,  the  scope  of 
the  recommendations,  the  benefits  of  adopting  them,  document  conven¬ 
tions,  and  comment  procedures. 

•  Section  2  includes  an  overview  of  the  software  architecture,  the  hard¬ 
ware  and  operating  system  assumptions,  a  summary  of  the  IV  service 
groups  addressed  by  the  command  set,  and  an  explanation  of  required 
and  optional  commands  and  parameters. 

•  Section  3  introduces  the  binary  and  ASCII  application  interfaces,  ex¬ 
plains  the  parameters  and  associated  values  used  by  the  interfaces,  and 
explains  how  to  use  the  interfaces. 

•  Section  4  covers  implementation  issues  including  software  installation, 
operating  system  issues,  and  ASCII  and  binary  interface  issues.  It  in¬ 
cludes  detailed  information  on  command  and  parameter  value  formats, 
buffer  behavior,  device  driver  modes,  and  binary  interface  interrupt 
settings. 

•  Section  5  includes  summary  tables  for  the  command  set  and  its  parame¬ 
ters  including  lists  of  available  commands  and  parameters  including 
their  token  numbers. 

•  Sections  6  through  9  contain  detailed  command  descriptions  for  the  sys¬ 
tem,  visual-management,  videodisc,  and  XY-input  device  service  groups, 
respectively. 

•  Appendix  A  gives  detailed  recommendations  on  graphics  registration  rel¬ 
ative  to  background  video. 

•  Appendix  B  summarizes  accepted  graphics  modes. 

•  Appendix  C  includes  brief  programming  examples  in  BASIC  and  C. 

•  Appendix  D  covers  error  handling  and  lists  error  numbers  with  mes¬ 
sages  and  explanations. 

Note:  Those  who  are  interested  primarily  in  the  command  set  should  read 
Section  1.4  and  all  of  Section  3  for  background  information  before  proceeding 
to  the  command  sections. 
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1 .4  Document  conventions 


Familiarity  with  the  conventions  used  in  this  document  will  aid  understand¬ 
ing.  These  conventions  are  discussed  below. 


Figures  and  tables  are  referenced  in  the  text  by  number.  Each  number  con¬ 
sists  of  the  major  section  number  followed  by  a  sequential  figure  or  table 
number  starting  with  one  for  each  major  section.  For  example,  Table  2-3  re¬ 
fers  to  the  third  table  in  Section  2.  Typically,  figures  and  tables  immediately 
follow  the  first  paragraph  in  which  they  are  referenced. 


The  term  “MS-DOS"  is  used  in  a  generic  sense  for  Microsoft  MS-DOS  ver¬ 
sions  2.0  and  higher  and  compatible  operating  systems  such  as  IBM  PC  DOS 
versions  2.0  and  higher. 


Numbers  are  given  either  in  hexadecimal,  binaiy,  or  decimal  format.  Hexa¬ 
decimal  numbers  have  an  “H”  suffix,  for  example  006FH.  Similarly,  binary 
numbers  have  a  “B”  suffix,  for  example  0001011B.  Decimal  numbers  are  writ¬ 
ten  without  a  suffix. 


Command  names  and  parameters  in  the  text  are  in  bold  face.  In  the  example 
vdPlay  from=1000,  vdPlay  is  a  command  and  from  is  a  parameter.  Com¬ 
mand  names  use  mixed  lower  and  upper  case  for  clarity,  while  parameters 
use  lower  case  only.  However,  case  is  not  significant. 


Examples  of  ASCII  interface  commands  include  calling  strings  and  return 
strings.  In  the  examples  semicolons  separate  commands  from  explanatory 
comments.  This  is  strictly  a  convention  of  convenience  and  does  not  imply 
that  the  semicolon  is  a  syntactic  comment  delimiter. 


Examples  of  binary  interface  commands  include  microprocessor  register  con¬ 
tents  when  the  interface  is  called  and  after  it  returns  control  to  the  applica¬ 
tion.  Again,  semicolons  separate  commands  from  explanatory  comments. 


The  binary  examples  use  memory  addresses  based  on  the  Intel  80x86  micro¬ 
processor  ES  and  DI  registers.  These  registers  are  used  for  the  addresses  of 
parameter  packets  that  contain  one  or  more  structures  each  consisting  of  a 
parameter  token  number  and  its  associated  value.  The  addresses  of  individ¬ 
ual  parameters  and  values  within  parameter  packets  are  given  as  hexadeci¬ 
mal  offsets  in  bytes  from  the  base  address  in  ES:DI.  For  example,  ES:DI[10] 
is  the  area  of  memory  10H  (16  decimal)  bytes  after  the  memory  location 
pointed  to  by  the  combined  segment  and  offset  address  in  ES:DI. 
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1 .5  Comment  submission 


To  succeed,  we  need  broad  industry  support  and  invite  detailed  commentary 
from  IV  developers,  manufacturers,  and  users.  Please  describe  questions  and 
concerns  fully  and  include  alternate  suggestions  and  options.  In  general,  we 
cannot  consider  blanket  criticisms  that  do  not  specify  the  natures  of  concerns 
or  suggest  alternatives.  For  example,  we  cannot  consider  “I  don’t  like  this 
command”  with  no  other  commentary  for  future  revisions. 

Steps  to  follow: 

1.  Designate  qualified  technical  representatives  within  your  organization 
who  can  ably  review  the  various  mqjor  sections  of  the  document. 

2.  Ask  your  technical  representatives  to: 

a.  Respond  to  the  recommendations  on  an  item-by-item  basis  for  your 
organization. 

b.  Furnish  a  list  of  questions,  comments,  and  suggestions,  referencing 
the  commands  by  name. 

c.  Furnish  a  list  of  questions,  comments,  and  suggestions  for  other  sec¬ 
tions  of  the  documents  referencing  document  number,  section  num¬ 
ber,  page  number,  and  paragraph. 

3.  Comments  must  be  submitted  in  writing  and  should  include  your  mailing 
address,  telephone  number,  and,  if  available,  fax  number. 

4.  To  ensure  that  your  comments  are  considered  and  that  your  organization 
receives  further  information  and  documents,  address  all  correspondence 
to  the  address  or  fax  number  given  in  the  accompanying  cover  letter.  (If 
the  cover  letter  is  not  available,  contact  the  publisher  given  on  the  copy¬ 
right  page.) 

5.  Along  with  your  comments  please  state  specific  areas  of  interest. 

It  may  be  useful  to  identify  several  technical  representatives  with  different  in¬ 
terests  and  backgrounds,  and  to  have  each  individual  or  group  review  sec¬ 
tions  in  their  areas  of  expertise.  This  may  make  in-depth  responses  easier 
than  having  several  individuals  review  the  entire  document. 
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2  System  overview 


Figure  2-1  shows  the  general  software  architecture  of  a  compliant  system/ 
The  recommended  practices  are  based  on  sets  of  high-level  commands  organ¬ 
ized  functionally  by  service  group.  These  commands  are  issued  by  an  applica¬ 
tion  and  passed  via  an  ASCII  or  binary  application  interface  to  the  Virtual 
Device  Interface  (VDI)  Management  Software.1  VDI  Management,  in  turn, 
executes  the  commands  by  calling  appropriate  low-level  services  and  passes 
responses  back  to  the  application  via  the  application  interface.  VDI  Manage¬ 
ment  is  responsible  for  making  different  delivery  platforms  functionally  com¬ 
patible  at  the  application  interface  level,  thus  enabling  the  implementation  of 
platform  independent  commands. 


Figure  2-1. 
The  general  software 
architecture  of  a 
compliant  system 


ASCII  or  Binary 
Application  Interface 
to 

VDI  Management  Software 


1 .  In  the  context  of  this  document,  the  term  "application”  includes  authoring  software  that  may  have  been 
used  to  develop  the  application. 
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2.1  Hardware  and  operating  system  assumptions 

The  recommended  practices  make  several  assumptions  about  the  computer, 
its  operating  system,  and  the  IV  hardware.  These  include: 

•  The  computer  is  based  on  an  Intel  80x86  processor  with  MS-DOS 
version  2.0  or  higher,  PC  DOS  version  2.0  or  higher,  or  a  functionally 
equivalent  operating  system. 

•  The  computer  uses  an  IBM  PC/AT-compatible  ROM  BIOS 

•  The  system  has  a  graphics/video  overlay  capability  using  CGA,  EGA,  or 
VGA  graphics,  or  uses  two  monitors,  one  with  video  and  the  other  with 
graphics. 

•  One  or  more  of  several  XY-input  devices  may  be  present  (touch  screen, 
mouse,  light  pen,  bit  pad,  or  other). 

•  One  or  more  videodisc  players  or  functionally  equivalent  video  sources 
may  be  present 

Although  this  document  describes  interfaces  for  MS-DOS,  we  realize  the  im¬ 
port  of  other  platforms.  IV  systems  based  on  the  Apple  II  and  the  Macintosh 
are  widely  used,  and  applications  for  OS/2  and  Microsoft  Windows  are  start¬ 
ing  to  appear.  Procurement  policies  of  the  U.S.  Government  will  encourage 
POSIX  applications,  and  applications  exist  for  UNIX,  VMS,  and  others. 

Therefore,  we  designed  the  recommended  practices  with  the  intent  to  adapt 
them  to  other  operating  systems  and  non-80x86  hardware  platforms.  The  gen¬ 
eral  structure  and  functionality  of  the  commands  are  transferable  to  other  en¬ 
vironments.  However,  substantial  portions  of  the  current  recommendations 
are,  of  necessity,  specific  to  MS-DOS. 


2.2  Interface  design  criteria 


The  criteria  used  in  designing  the  interfaces  in  the  recommended  practices 
include: 

1.  The  recommended  practices  should  not  keep  application  authors  from 
choosing  appropriate  languages  for  the  tasks  at  hand.  Compatible  lan¬ 
guages  should  include,  but  not  necessarily  be  limited  to,  general  pur¬ 
pose  programming  languages,  computer-based  training  (CBT)  authoring 
systems,  artificial  intelligence  (AI)  tools,  prototyping  systems,  and 
database  managers. 

2.  Access  mechanisms  should  be  as  consistent  as  possible,  both  for  a  single 
operating  system  and  across  different  operating  systems. 

3.  It  should  be  possible  to  upgrade  the  recommended  practices  as  required  by 
technological  developments  without  affecting  existing  applications. 


Section  2.  System  overview 


4.  The  recommended  practices  should  include  both  simple,  easy-to-use 
commands  for  doing  simple  tasks  and  sophisticated  functions  to  support 
the  most  demanding  IV  applications. 

5.  The  commands  should  not  depend  on  any  one  operating  system,  though 
the  interfaces  must  to  some  extent  be  specific  to  individual  operating 
systems. 

6.  Except  for  features  that  affect  the  application  interfaces,  the  recom¬ 
mended  practices  should  not  require  a  specific  VDI  Management  soft¬ 
ware  architecture. 

7.  Hardware-specific  assumptions  should  be  defined  in  detail. 

8.  Memory  requirements  and  performance  costs  should  be  kept  to  a  mini¬ 
mum.  Therefore,  implementation  decisions  should  side  with  simplicity 
when  possible. 

We  have  used  these  criteria  to  define  a  software  platform  that  should  furnish 
a  high  degree  of  portability  for  a  variety  of  IV  applications  while  keeping  im¬ 
plementation  costs  and  run-time  resource  requirements  to  a  minimum. 


2.3  The  rationale  for  two  interfaces 


The  goal  of  supporting  a  variety  of  programming  languages  led  us  to  propose 
that  for  MS-DOS  one  interface  should  include  an  installable  device  driver  ca¬ 
pable  of  standard,  ASCII  communications.  Some  programming  systems,  in¬ 
cluding  several  popular  interpreters,  have  primitive  facilities  for  interfacing 
with  other  software.  However,  almost  all  programming  systems  can  access 
files  and,  therefore,  use  device  drivers. 

More  sophisticated  programming  systems  that  can  issue  software  interrupts 
should  have  a  more  efficient  interface  available.  This  is  the  binary  interface 
that  accesses  VDI  Management  through  a  software  interrupt. 

In  the  current  recommended  practices  the  command  list  is  the  same  for  both 
interfaces,  but  additional  parameters  are  available  to  binary  interface  pro¬ 
grammers.  For  example,  the  binary  interface  can  pass  an  entire  palette  as  a 
pointer  to  an  array  of  individual  palette  colors.  This  is  difficult  to  express 
with  ASCII  strings  and,  therefore,  not  supported  by  the  ASCII  interface. 

However,  each  command  name  in  the  ASCII  interface  has  a  binary  interface 
token  number  that  furnishes  either  the  same  functionality  or  a  superset 
thereof.  Each  ASCII  parameter  name  has  a  corresponding  binary  parameter 
token  number.  The  high  degree  of  consistency  between  the  two  interfaces 
should  simplify  their  implementation  and  use. 

In  future  versions,  we  would  not  rule  out  commands  that  are  available  from 
the  binary  interface  only.  However,  the  facilities  furnished  by  the  ASCII  in¬ 
terface  will  remain  a  strict  subset  of  those  available  from  the  binary  interface. 
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2.4  Service  groups  and  command  organization 


Commands  that  map  to  related  services  are  separated  into  service  groups. 
Systems  suppliers  and  applications  developers  can  use  only  those  service 
groups  that  include  functions  required  for  a  given  application.  This  organiza¬ 
tion  also  supports  adding  new  service  groups  in  a  modular  fashion  as  new  ca¬ 
pabilities  become  generally  available.  Examples  of  service  groups  that  may 
be  considered  for  future  addition  include:  windowing  environments  and 
graphical  user  interfaces,  audio  management,  digital  audio,  and  digital  video. 

Currently,  the  recommended  practices  include  four  service  groups:  general 
system  (sy),  visual  management  (vm),  videodisc  (vd),  and  XY-input  device 
(xy).  The  sy  service  group  does  system-level  hardware  and  software  initializa¬ 
tion,  furnishes  information  about  the  availability  of  other  service  groups,  im¬ 
plements  a  command  queue,  and  has  commands  to  help  with  error  handling. 
The  other  groups  address  the  functional  areas  for  which  they  are  named. 
However,  Hie  groupings  are  for  convenience  of  organization  and  do  not  neces¬ 
sarily  dictate  which  hardware  must  actually  perform  the  commands. 


The  general  system  group  (sy)  is  the  only  group  that  must  be  included  in  all 
compliant  implementations. 


System  suppliers  are  responsible  for  ensuring  correct  installation  of  system 
hardware  and  software  and  for  making  a  list  of  installed  service  groups  avail¬ 
able  to  the  application  through  the  system  commands.  System  suppliers  also 
must  include  a  way  for  users  to  assign  contiguous,  logical  numbers  starting 
with  zero  to  specific  devices  within  a  service  group  when  more  than  one  such 
device  is  present  Note  that  this  lets  users  specify  the  order  of  devices  within 
each  class,  but  does  not  let  users  assign  arbitrary  numbers  to  the  devices. 
(Section  4  covers  these  issues  in  detail.) 


2.5  Core  and  extended  commands  and  parameters 

The  command  set  includes  both  core  and  extended  commands.  Individual 
commands,  in  turn,  may  include  both  core  and  extended  parameters. 

Core  commands  in  a  given  service  group  furnish  the  general  functionality  re¬ 
quired  by  IV  applications.  If  a  given  service  group  is  implemented,  all  core 
commands  for  the  group  must  be  included  for  the  implementation  to  be  com¬ 
pliant  Similarly,  if  a  command  is  implemented,  all  core  parameters  for  the 
command  must  be  included. 

Extended  commands  and  parameters  are  nonportable.  They  are  provided  for 
developers  who  need  to  produce  both  portable  courseware  and  applications 
that  need  special,  nonportable  capabilities,  or  who  want  to  take  advantage  of 
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these  capabilities  if  present  and  properly  handle  their  absence.  Extended  com¬ 
mands  and  parameters  are  not  required  for  compliancy.  However,  an  ex¬ 
tended  command  may  include  core  parameters  so  that  the  command’s 
inclusion  is  optional,  but,  if  it  is  included,  the  inclusion  of  the  core  parame¬ 
ters  is  mandatory. 


Because  manufacturers  must  support  core  commands  and  parameters  as  a 
prerequisite  to  supporting  extended  commands  and  parameters,  developers  can 
write  both  portable  and  nonportable  applications  using  the  same  tools,  authoring 
systems,  and  custom  libraries. 


Note:  Some  extended  commands  and  parameters  may  be  under  consideration 
for  future  inclusion  in  the  core  command  set.  However,  we  do  not  guarantee 
that  they  will  be  included.  An  application  that  relies  on  these  commands  and 
parameters  is  noncompliant.  However,  an  application  that  uses  extended  com¬ 
mands  or  parameters  when  present  and  still  executes  properly  in  their  ab¬ 
sence  is  compliant. 
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3  Using  the  interfaces 


The  recommended  practices  include  two  interfaces  for  MS-DOS,  the  binary 
interface  and  the  ASCII  interface.  By  providing  two  interfaces,  the  recom¬ 
mended  practices  can  be  used  with  a  variety  of  programming  languages.  Lan¬ 
guages  that  can  issue  interrupts  will  typically  use  the  binary  interface  for 
speed  and  efficiency.  Languages  without  this  capability  can  use  standard  file 
I/O  and  ASCII  strings  with  the  ASCII  interface.  The  basic  characteristics  of 
each  interface  are: 

•  The  binary  interface:  Applications  communicate  with  VDI  Manage¬ 
ment  by  passing  and  receiving  binary  values  across  a  software  interrupt. 

The  binary  interface  uses  an  assignable  software  interrupt  in  the  range 
60H  to  66H  to  request  VDI  Management  software  services.  An  applica¬ 
tion  loads  the  microprocessor's  registers  with  a  command  code  request¬ 
ing  a  specific  service  and  a  pointer  to  a  parameter  packet  containing 
parameter  codes  and  values. 

•  The  ASCII  interface:  Applications  communicate  with  VDI  Manage¬ 
ment  through  a  device  driver  using  file  I/O  and  ASCII  strings. 

The  ASCII  interface  uses  an  MS-DOS  device  driver  for  communications 
between  the  application  and  VDI  Management.  The  application  writes 
command  strings  to  and  reads  response  strings  from  the  device  driver. 

A  command  string  consists  of  a  command  name  followed  by  parameters 
and  values. 

The  rest  of  this  section  explains  how  to  use  both  interfaces.  Section  4  gives  de¬ 
tailed  information  on  implementing  the  interfaces. 


3.1  An  introduction  to  parameters  and  values 


Both  interfaces  use  labeled  parameters  and  associated  values.  Parameters 
may  have  associated  calling  values,  return  values,  or  both.  Every  parameter 
value  passed  to  VDI  Management  is  associated  with  a  parameter  identifier. 
Therefore,  only  those  parameters  that  are  actually  required  by  the  command 
need  be  specified. 
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Consider  the  vdPlay  command,  binary  interface  token  number  3081.  vdPlay 
instructs  the  player  to  play  a  video  segment.  Applications  can  accompany  this 
command  with  several  optional  parameters  including  from,  to,  and  speed. 


A  from  parameter  and  its  associated  value  causes  the  player  to  search  to  a 
specified  frame  before  entering  play  mode.  Without  the  from,  the  play  starts 
with  the  frame  that  is  current  when  the  application  issues  the  command.  A 
to  parameter  causes  the  player  to  play  to  a  specified  frame  and  stop.  Without 
the  to,  the  play  continues  until  the  application  intervenes  or  the  player 
reaches  the  edge  of  the  videodisc.  With  a  speed  parameter,  the  segment 
plays  at  the  specified  speed.  Without  a  speed,  the  segment  plays  at  the  nor¬ 
mal  speed  of  either  30  or  25  frames  per  second  depending  on  the  video  stan¬ 
dard,  NTSC  or  PAL,  respectively. 

With  the  ASCII  interface  each  parameter  value  must  be  preceded  by  a  param¬ 
eter  name  so  that  a  parser  can  decipher  the  supplied  arguments.  However, 
each  parameter  name  does  not  necessarily  require  an  associated  value.  Some 
parameters  used  to  query  the  system  do  not  have  associated  values.  A  com¬ 
mand  string  is  variable  in  length  with  its  length  determined  by  the  number 
of  parameters  and  values. 


With  the  binary  interface  the  parameter  packet  is  an  array  of  parameter 
structures.  Each  structure  contains  a  parameter’s  numeric  identifier  and  the 
parameter's  value  or,  for  parameters  without  associated  calling  values,  the 
space  for  a  return  value.  The  minimum  parameter  packet  size  depends  on  the 
number  of  parameters. 


Continuing  the  vdPlay  example,  to  use  the  ASCII  interface  to  play  from  the 
current  frame  to  the  edge  of  the  disk  or  until  a  vdStill  command  is  issued  re¬ 
quires  simply: 

vdPlay 

To  search  to  frame  1000,  then  play  to  frame  1500  use: 
vdPlay  from=1 000,  to=1 500 1 

In  the  first  case  above,  the  binary  interface  does  not  pass  a  parameter  packet 
with  vdPlay.  In  the  second  case,  it  passes  a  packet  containing  four  32-bit 
memory  blocks.  The  first  block  contains  the  24  decimal,  the  token  number  for 
the  from  parameter.  The  second  block  contains  1000,  the  value  of  from.  The 
third  block  contains  48,  the  token  number  for  the  to  parameter,  and  the 
fourth  contains  1500,  the  value  of  to. 


1.  Or  vdPlay  from  lOOO  to  1500;  vdPlay  from,  1000,  to,  1500 ;  or  VDPLAY  TO  1500  FROM  1000.  All  are 
equivalent,  case  and  parameter  order  are  not  significant,  and  equals  signs  and  commas  are  optional. 
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With  both  the  binary  and  ASCII  interfaces,  the  order  of  parameters  is  insig¬ 
nificant.  For  example: 

vdPlay  from=1000,  to=2000 
and: 

vdPlay  to=2000,  from=1 000 
execute  identically. 

Note:  Because  order  is  insignificant,  supplying  a  parameter  more  than  once 
in  a  command  string  or  parameter  block  is  an  error.  This  simplifies  designing 
VDI  Management  parsers  and  indirectly  establishes  the  maximum  number  of 
parameters  that  can  be  passed  to  either  interface  in  a  single  call.  This  maxi¬ 
mum  is  equal  to  the  number  of  parameters  for  the  single  command  with  the 
largest  number  of  defined  parameters. 


3.2  Using  the  binary  interface 


This  section  explains  how  to  use  the  binary  interface  under  MS-DOS  and 
gives  detailed  information  on  parameter  packets  and  processor  registers. 


3.2.1  General  procedure 


Applications  will  typically  take  the  following  steps  to  call  VDI  Management 
through  the  binary  interface: 

1.  Build  in  application  memory  a  packet  containing  parameter  token  num¬ 
bers  and  values  to  pass  to  VDI  Management  with  the  command. 

2.  Load  the  token  number  for  the  command  into  the  AX  register. 

3.  Load  the  number  of  parameters  contained  in  the  packet  into  the  BX 
register. 

4.  Load  the  segment  and  offset  address  of  the  parameter  packet  into  the 
ES:DI  register  pair.  (The  segment  address  goes  in  ES  and  the  offset  rela¬ 
tive  to  that  segment  goes  in  DI.) 

5.  Issue  the  appropriate  software  interrupt. 

6.  On  return  from  the  software  interrupt,  check  the  value  of  AX.  If  AX  is  non¬ 
zero,  it  contains  an  error  code  (see  Section  D),  and  the  application 
should  take  appropriate  action  to  recover. 

The  software  interrupt  used  depends  on  the  contents  of  the  environment 
space.  (See  Section  4.4.1  for  details.) 
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3.2.2  Confirming  that  the  binary  interface  exists _ 

Calling  the  binary  interface  through  its  interrupt  vector  could  have  dire  re¬ 
sults  if  the  interface  is  not  installed.  Therefore,  applications  that  use  this 
interface  need  a  way  to  confirm  its  existence  without  calling  it  with  a  com¬ 
mand  such  as  sylnit.  To  this  end,  the  binary  interface  includes  a  16-byte  sig¬ 
nature  of  the  form: 

IWERnnn... 

where  “nnn...”  is  restricted  to  ASCII  decimal  digits  (ASCII  30H-39H),  the  de¬ 
cimal  point  (ASCII  2EH),  and  terminal  NUL  (ASCII  00H)  characters  to  pad 
to  16  bytes  if  necessary.  This  is  the  official  version  number  for  the  recom¬ 
mended  practices  implemented  by  VDI  Management  as  it  would  be  returned 
by  the  command  syGetState  iwer  (see  Section  6).  The  version  number  for 
the  current  recommendations  is  “1.0”,  which  yields  a  signature  of: 

IWER1.0 

followed  by  eight  NULL  characters. 

This  signature  resides  at  the  address  pointed  to  by  the  IVINT  interrupt  vec¬ 
tor  minus  10H.  (See  Section  4.4.1  for  more  information  on  IVINT.) 

Note:  To  confirm  that  the  binary  interface  is  installed,  an  application  must 
determine  the  address  pointed  to  by  IVINT,  then  retrieve  the  information 
stored  in  the  16-byte  paragraph  immediately  preceding  that  address.  (We  as¬ 
sume  that  languages  that  use  the  binaiy  interface  have  this  capability.) 


3.2.3  Parameter  packets 


A  parameter  packet  contains  8  bytes  of  memory  for  each  parameter.  The 
8-bytes  are  divided  into  two  32-bit  blocks.  The  first  32-bits  contain  the 
parameter  token  number;  the  second  32-bits  contain  the  parameter  value. 
(Section  4.4.2  gives  detailed  information  on  parameter  value  formats.) 

Parameter  token  numbers  are  constants,  as  defined  in  Section  5.2.  VDI  Man¬ 
agement  uses  them  to  determine  which  parameters  the  application  is  pass¬ 
ing.  Parameter  values  may  take  different  types  depending  on  the  information 
being  passed.  Valid  types  include  signed  and  unsigned  32-bit  integers,  point¬ 
ers  consisting  of  a  16-bit  segment  and  a  16-bit  offset,  and  signed  32-bit  frac¬ 
tional  numbers. 

For  example,  assume  an  application  has  initialized  VDI  Management  and  dis¬ 
played  video  on  the  monitor,  and  now  decides  to  play  a  video  segment  start¬ 
ing  at  frame  1000  and  ending  at  frame  2000.  The  application  sets  up  the 
registers  and  parameter  packet  as  follows: 

AX  3081  ;  token  number  of  vdPlay  command 

BX  2  ;  packet  contains  two  parameters 
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ES:DI  is  a  pointer  to  a  packet  containing: 


Block  1 

24 

;  token  number  of  from  parameter 

Block  2 

1000 

;  value  of  from  parameter 

Block  3 

48 

;  token  number  of  to  parameter 

Block  4 

2000 

;  value  of  to  parameter 

(Note:  All  values  in  the  above  example  use  decimal  notation.) 

The  length  of  the  parameter  packet  varies  with  the  number  of  parameters.  A 
packet  with  five  parameters  is  laid  out  as  shown  in  Table  3-1.  Longer  pack¬ 
ets  are  possible  by  simply  adding  the  extra  parameters  at  the  end. 


Table  3-1. 
Example  parameter 
block  layout. 


Address 

Contents 

ES:DI[0] 

Parameter  1  token  number 

ES:DI[4] 

Parameter  1  value 

ES:DI[8J 

Parameter  2  token  number 

ES:DI[C] 

Parameter  2  value 

ES:DI[10] 

Parameters  token  number 

ES:DII14J 

Parameter  3  value 

ES:DI[18] 

Parameter  4  token  number 

ES:DI[1C] 

Parameter  4  value 

ES:DI[20] 

Parameter  5  token  number 

ES:DI[24] 

Parameter  5  value 

To  determine  how  much  memory  to  allocate  for  a  parameter  block  that  can 
handle  any  command  for  the  binary  interface,  multiply  the  maximum  num¬ 
ber  of  parameters  that  can  be  passed  by  any  command  by  the  memory  re¬ 
quired  for  one  parameter.  For  example,  assume  that  syBigCommand  has 
the  longest  parameter  list  at  22  parameters.  Each  parameter  uses  4  bytes  for 
its  token  number  and  4  for  its  value.  Therefore,  allocate  8  x  22  bytes  or  a  176- 
byte  block. 

Registers  other  than  AX,  BX  and  ES:DI  are  insignificant  and  may  contain 
any  value.  If  a  command  has  no  parameters,  BX  is  zero  and  ES:DI  are  insig¬ 
nificant  On  return,  all  registers  are  unchanged  except  AX.  AX  contains  zero 
if  the  command  was  successful,  or  an  error  code  indicating  a  problem.  When 
VDI  Management  rounds  values,  it  changes  the  values  in  the  parameter 
packet  in  application  memory  to  the  rounded  values.  (See  the  service  group 
command  sections  for  more  information  on  rounding.) 


2.  Note  that  addresses  of  parameter  tokens  and  value  within  a  packet  are  described  as  hexadecimal  offsets  in 
bytes  from  the  base  address  in  ES:DI.  For  example,  ESJ3I[20]  is  the  area  of  memory  20H  (32  decimal)  bytes 
after  the  location  pointed  to  by  ES:DI.  Each  32-bit  block  uses  4  bytes,  so  this  is  the  fifth  block  in  the  packet. 
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3.2.4  Return  values  to  parameters 


The  contents  of  a  parameter  packet  change  depending  on  the  nature  of  the 
command.  Some  commands,  such  as  vdGetState,  return  information  to  the 
application.  When  such  a  command  executes,  the  application  passes  a  param¬ 
eter  packet  with  sufficient  space  for  the  requested  information.  The  space  is 
allocated  using  the  format  described  in  Section  3.2.3. 


A  parameter/value  structure  both  defines  the  requested  information  and  fur¬ 
nishes  a  return  location.  On  entry  into  VDI  Management,  the  parameter 
value  is  insignificant  and  can  be  any  value.  When  VDI  Management  has 
derived  the  requested  value,  either  by  calculation  or  by  interrogating  the 
hardware,  it  puts  the  value  into  the  appropriate  parameter  value  block. 


For  vdGetState  frame,  the  application  might  pass: 

AX  3078  ;  token  number  of  vdGetState  command 

BX  1  ;  packet  contains  one  parameter 

ES:DI[0]  23  ;  token  number  of  frame  parameter 

ES:DI[4]  Can  be  any  value 

On  return,  the  values  might  be: 

AX  0  ;  command  executed  correctly 

BX  1  ;  packet  contains  one  parameter 

ES:DI[0]  23  ;  token  number  of  frame  parameter 

ES:DI[4]  1 2345  ;  frame  number  1 2345  is  currently  displayed 

(Note:  All  values  in  the  above  example  use  decimal  notation.) 


Applications  should  check  AX  and  assume  that  if  an  erroT  has  occurred 
(AX  *  0),  any  values  returned  in  the  packet  are  meaningless. 


Note  1:  If  the  binary  interface  returns  a  pointer  to  a  string,  the  string  is  in 
upper  case.  This  is  an  arbitrary  decision  to  make  return  strings  easier  to 
parse  and  to  make  binary  and  ASCII  return  strings  consistent. 


Note  2:  VDI  Management  may  round  parameters  such  as  play  speeds.  If  so, 
VDI  Management  changes  the  values  in  the  parameter  packet  to  the  actual 
values  used  after  rounding  and  subsequent  queries  return  actual  values  in¬ 
stead  of  requested  values. 
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3.3  Using  the  ASCII  interface _ 

This  section  explains  how  to  use  the  ASCII  interface  under  MS-DOS  and  in¬ 
cludes  an  explanation  of  command  and  response  strings. 

3.3.1  General  procedure _ 

To  issue  commands  to  VDI  Management  via  the  ASCII  interface,  applications 
use  standard  file  I/O  to  communicate  with  a  device  driver  named  IVDEV.  Ap¬ 
plications  will  typically  take  the  following  steps  to  call  VDI  Management 
through  the  ASCII  interface: 

1.  Format  a  command  string  specifying  the  required  function. 

2.  Open  the  device  driver  for  writing. 

3.  Write  the  command  string  to  the  device  driver. 

4.  Close  the  device  driver. 

5.  Open  the  device  driver  for  reading. 

6.  Read  the  response  string  from  the  device  driver. 

7.  Close  the  device  driver. 

8.  Parse  the  response  string.  If  the  string  is  “OK”  or  contains  expected  re¬ 
turn  values,  continue  processing  normally.  If  the  string  is  “ERROR  n...” 
where  “n...”  is  an  error  number,  take  action  to  recover  from  the  error. 

The  exact  method  of  communicating  with  the  driver  depends  on  the  program¬ 
ming  system. 

3.3.2  Confirming  that  the  ASCII  interface  exists _ 

Applications  that  use  the  ASCII  interface  must  be  able  to  confirm  that  the 
interface  and  its  associated  device  driver,  IVDEV,  are  properly  installed.  Sim¬ 
ply  verifying  that  IVDEV  can  be  opened  is  insufficient  because  some  lan¬ 
guages  may  automatically  create  IVDEV  if  it  does  not  exist.  Therefore,  an 
application  should  open  the  file,  write  an  sylnit  command  to  it  (see  Sec¬ 
tion  6),  and  read  the  response  string. 

•  If  the  response  string  consists  of  the  ASCII  characters  “OK”  followed  by 
CR/LF,  sylnit  was  successful.  The  application  should  continue  normally. 

•  If  the  response  string  consists  of  “ERROR  n. . .”  where  “n. . .”  is  an  error 
number  followed  by  CR/LF,  then  the  ASCII  interface  is  installed,  but 
VDI  Management  could  not  be  initialized,  indicating  improper  installa¬ 
tion  or  improper  use  of  sylnit.  The  application  should  handle  the  error, 
probably  by  displaying  an  error  message  and  exiting. 

•  If  the  function  used  to  read  IVDEV  returns  a  read  error  or  the  response 
string  consists  of  anything  other  than  “OK”  or  “ERROR  n..."  either  the 
device  driver  is  not  installed  or  serious  problems  exist  with  VDI  Manage- 
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ment.  Some  languages  may  automatically  create  a  file  named  IVDEV  if 
the  driver  is  not  installed.  The  application  should  politely  exit  with  an 
error  message  and,  if  necessary,  delete  the  bogus  file  (preferred)  or  at 
least  tell  the  user  that  a  bogus  IVDEV  file  may  have  been  created. 

Note:  If  IVDEV  is  not  installed  and  a  file  of  the  same  name  is  automatically 
created,  it  will  contain  the  string  the  application  tried  to  write  to  the  driver. 
If  this  happens,  and  IVDEV  is  then  installed  as  a  device  driver,  the  bogus  file 
cannot  be  deleted  from  the  command  line  because  MS-DOS  will  assume  it  is 
supposed  to  delete  the  device  driver,  which  is  illegal.  Therefore,  the  file  must 
be  deleted  with  the  device  driver  unloaded. 


3.3.3  Command  strings 


A  command  string  is  a  series  of  printable  ASCII  characters  terminated  with 
a  carriage  return  (CR,  ASCII  ODH).  The  ASCII  interface  discards  line  feeds 
(LF,  ASCII  OAH)  following  the  CR.  The  string  starts  with  a  command  name, 
typically  followed  by  a  parameter  list.  (Section  4.3  gives  detailed  information 
on  formal  command  string  syntax  and  parameter  value  data  types.) 


Assume  an  application  has  initialized  VDI  Management  and  turned  video  on. 
To  play  a  videodisc  segment  starting  at  frame  1000  and  ending  at  frame 
2000,  the  application  could  issue  the  command  string: 

vdPlay  from*1 000.  to=2000 

vdPlay  is  the  command  name.  It  corresponds  to  the  token  number  passed  in 
the  AX  register  with  the  binary  interface.  The  substrings  from  and  to  are  pa¬ 
rameter  labels  used  by  VDI  Management  to  determine  which  parameters  are 
being  passed.  The  substrings  “1000”  and  “2000”  are  parameter  values.  Each 
value  is  associated  with  the  preceding  label,  so  1000  is  the  value  of  from  and 
2000  is  the  value  of  to. 

Because  the  string  ends  with  CR,  VDI  Management  can  determine  how  many 
parameters  the  application  is  passing  by  inspection.  Unlike  the  binary  inter¬ 
face,  the  ASCII  interface  does  not  require  a  parameter  count. 


3.3.4  Response  strings 


Response  string  contents  from  the  ASCII  interface  depend  on  the  nature  of 
the  command  string.  If  the  command  was  correct  and  did  not  ask  for  informa 
tion,  the  response  string  is  “OK".  If  the  command  asked  for  information,  the 
ASCII  interface  returns  a  series  of  comma-separated  parameter  values.  If  an 
error  occurred,  the  response  string  consists  of  “ERROR”  followed  by  a  space, 
followed  by  the  error  number  as  ASCII  digits.  All  response  strings  end  with 
CR/LF. 
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For  example,  consider: 
vdPlay  from=l  000,  to«2000 

If  this  executes  correctly,  the  ASCII  interface  returns  “OK”.  However,  the 
command: 

vdPlay  from=1000,  from=2000 

generates  the  response  string  “ERROR  54”  (Parameter  used  more  than  once). 

If  an  application  issues  the  command: 
vmGetState  vlevel  glevel 

which  asks  about  graphics  and  video  fade  levels,  the  response  might  be 
“255,200”.  This  says  that  the  video  level  is  255  and  the  graphics  level  is  200. 

Note:  All  alpha  characters  returned  by  the  ASCII  interface  are  upper  case. 
This  is  an  arbitrary  decision  to  make  return  strings  easier  to  parse  and  con¬ 
sistent  between  implementations. 


3.4  Mixing  ASCII  and  binary  commands 


For  a  VDI  Management  module  to  be  compliant,  it  must  furnish  both  the  de¬ 
vice  driver  and  software  interrupt  access  methods,  although  both  do  not  have 
to  be  installed.  If  both  methods  are  loaded,  VDI  Management  should  behave 
correctly  when  an  application  mixes  ASCII  and  binary  commands. 


For  example,  if  an  application  issues  syQueue  on  via  the  binary  interface 
then  issues  a  series  of  commands  to  the  device  driver,  the  commands  issued 
via  the  driver  should  be  queued  correctly.  Similarly,  an  ASCII  command  and 
its  binary  counterpart  should  behave  identically  assuming  both  commands 
have  the  same  parameters  available. 

To  conserve  memory  and  enhance  performance,  applications  that  use  only 
one  interface  should  clearly  state  whether  the  ASCII  or  binary  interface 
should  be  installed.  Application  vendors  also  should  state  the  amount  of  mem¬ 
ory  required  by  the  application  after  VDI  management  has  been  loaded  to 
alert  users  of  any  potential  memory  problems. 
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This  section  discusses  implementation  details  for  VDI  Management  and  the 
ASCII  and  binary  interfaces.  It  includes  installation  issues,  operating  system 
requirements  and  reentrancy  issues,  ASCII  string  and  parameter  value  for¬ 
mats,  device  driver  buffer  behavior  and  communications  modes,  establishing 
the  binary  software  interrupt  number,  and  binary  data  types  and  formats. 


4.1  Installation  issues 


Installation  issues  include  the  installation  of  VDI  Management  and  assigning 
logical  device  numbers  at  the  time  of  installation.  The  following  subsections 
discuss  these  issues. 


4.1 .1  VDI  Management  installation 


Specific  methods  of  installing  VDI  Management  are  outside  the  scope  of  the 
recommended  practices.  VDI  developers  can  use  any  appropriate  method. 
Two  obvious  possibilities  are  terminate-and-stay-resident  (TSR)  software  and 
software  that  takes  an  application  name  as  a  command-line  parameter  and 
spawns  the  application. 


For  applications  that  use  the  binary  interface  only,  the  device  driver  need  not 
be  loaded.  Similarly,  for  applications  that  use  the  ASCII  interface  only,  the  bi¬ 
nary  interface  need  not  be  loaded. 


Although  VDI  implemented  must  supply  both  interfaces  for  an  implementation  to 
be  compliant,  both  do  not  have  to  be  installed  in  the  IV  system. _ 
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4.1.2  Logical  device  numbers 


Some  commands  accept  a  logical  device  number  as  a  parameter.  These  in¬ 
clude  videodisc  commands,  which  may  be  used  on  systems  with  multiple 
videodisc  players,  and  XY-input  commands,  which  may  be  used  on  systems 
with  multiple  XY-input  devices. 

Often,  applications  will  need  to  know  the  relationship  between  device  num¬ 
bers  and  physical  devices.  For  example,  if  a  system  includes  both  NTSC  and 
PAL  videodisc  players,  an  NTSC  application  should  ensure  that  it  controls 
the  NTSC  player. 


When  logical  device  numbers  are  allocated,  VDI  Management  lets  users  as¬ 
sign  numbers  to  specific  devices  using  an  appropriate  setup  facility.  Device 
numbers  must  be  contiguous  and  start  at  zero,  but  VDI  Management  does  not 
make  any  other  assumptions  about  logical-to-physical  device  mapping. 


Providing  a  set-up  facility  for  users  to  assign  logical  device  numbers  and  requiring 
contiguous  device  numbers  starting  with  zero  are  compliance  requirements. 


Because  of  the  range  of  available  physical  devices  and  the  need  to  furnish  on¬ 
going  support  for  existing  applications,  it  is  impossible  to  prescribe  a  general 
way  for  applications  to  examine  or  change  the  device  number  mapping.  If  an 
application  asks  for  the  device  type  and  discovers  a  device  that  was  not  in¬ 
vented  when  the  application  was  written,  it  cannot  possibly  use  this  informa¬ 
tion  while  executing.  Therefore,  application  authors  must  clearly  state  any 
requirements  for  a  particular  device  number  mapping,  so  that  users  can  set 
up  VDI  Management  appropriately. 


For  example,  assume  that  a  system  has  two  XY-input  devices,  a  mouse  and  a 
touchscreen.  Also  assume  that  the  mouse  is  installed  as  device  zero  and  the 
touchscreen  as  device  one.  An  application  that  requires  the  touchscreen  to  be 
device  zero  cannot  change  the  logical  numbering  at  run  time.  Therefore,  the 
application  author  must  clearly  inform  the  user  that  the  touchscreen  must  be 
installed  as  device  zero  when  the  user  installs  VDI  Management 


If  an  application  needs  information  about  the  mapping,  it  must  have  a  mecha-  • 

nism  for  the  user  to  provide  that  information.  Appropriate  techniques  include 
command-line  parameters  and  files  in  application-specific  formats.  If  neces¬ 
sary,  well  written  applications  should  use  an  installation  program  that  asks 
which  logical  device  number  to  use  for  each  peripheral.  Well  documented  ap¬ 
plications  should  carefully  explain  what  kinds  of  physical  devices  are  appro¬ 
priate  for  each  selection  in  the  installation  procedure.  ® 
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4.2  Operating  system  issues _ 

Operating  system  issues  include  basic  operating  system  requirements  and 
considerations  about  the  lack  of  reentrancy  under  MS-DOS.  The  following 
subsections  discuss  these  issues. 

4.2.1  Operating  system  requirements _ 

To  support  the  MS-DOS  version  of  the  recommended  practices,  the  operating 
system  must  be  MS-DOS  version  2.0  or  later  or  a  functionally  equivalent  op¬ 
erating  system.  Versions  of  MS-DOS  prior  to  2.0  cannot  use  installable  de¬ 
vice  drivers.  Therefore,  systems  that  cannot  run  MS-DOS  2.0  or  later  cannot 
comply  with  the  MS-DOS  version  of  the  recommended  practices  regardless  of 
the  attached  IV  hardware. 

Developers  may  provide  VDI  Management  software  that  requires  a  specific 
version  of  MS-DOS.  We  would  describe  this  as  either  “Compliant  only  when 
used  with  MS-DOS  version  N.nn"  or,  more  often,  “Compliant  only  when  used 
with  MS-DOS  version  N.nn  or  later.”  Such  software  should  test  the  MS-DOS 
version  number  and  decline  to  execute  if  it  is  not  supported.  Similarly,  appli¬ 
cation  authors  may  require  a  specific  version  of  MS-DOS.  Therefore,  users  of 
IV  hardware  and  courseware  should  ensure  that  the  versions  of  MS-DOS, 

VDI  Management,  and  courseware  that  they  purchase  are  compatible. 

4.2.2  MS-DOS  reentrancy  limitations _ 

At  certain  times — specifically  when  MS-DOS  has  suspended  processing  a 
function  request  to  service  an  interrupt — programs  are  not  allowed  to  call 
MS-DOS.  Consider  the  tick  chain.  Approximately  18  times  per  second,  the  op¬ 
erating  system  calls  all  routines  on  the  tick  chain.  Tick  routines  that  call  MS- 
DOS  must  check  the  MS-DOS  critical  section  flag  to  ensure  that  they  do  not 
call  MS-DOS  at  an  inappropriate  time. 

Typically,  high-level  programmers  need  not  be  concerned  about  such  issues. 
Unless  a  program  includes  interrupt  handlers  or  tick  routines,  it  will  not 
have  control  when  MS-DOS  cannot  be  called.  If  a  programming  system  links 
an  interrupt  automatically,  the  system’s  design  ensures  that  conflicts  are 
handled  correctly.  Also,  programmers  who  simply  call  MS-DOS  or  BIOS  func¬ 
tions  using  standard  methods  will  not  encounter  problems.  However,  those 
who  use  the  tick  chain  or  change  MS-DOS  or  BIOS  interrupt  vectors  must 
deal  with  the  lack  of  reentrancy. 

VDI  Management  assumes  it  can  call  MS-DOS  during  any  call  to  the  binary 
interface.  Therefore,  application  software  must  not  call  the  binary  interface 
when  it  is  unsafe  to  call  MS-DOS  or  when  a  previous  call  to  VDI  Manage¬ 
ment  has  been  interrupted.  If  an  application  installs  interrupt  handlers,  it 
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must  provide  mechanisms  to  ensure  that  VDI  Management  is  called  at  appro¬ 
priate  times  only. 

If  VDI  Management  does  any  background  processing  outside  of  application 
calls,  it  must  ensure  that  MS-DOS  is  called  only  when  it  is  safe  to  do  so. 

Also,  the  device  driver,  which  is  loaded  within  MS-DOS,  must  not  be  called 
at  those  times  when  it  is  unsafe  to  call  MS-DOS  or  when  VDI  Management 
has  been  interrupted. 

VDI  Management  may  need  to  do  some  background  processing,  and  the  de¬ 
vice  driver  may  have  to  do  some  work  of  its  own  to  overcome  reentrant  limi¬ 
tations.  For  example,  assume  an  ASCII  command  uses  the  filing  system. 
Within  a  device  driver,  the  MS-DOS  filing  system  is  already  executing  and 
may  not  be  reentered.  If  the  device  driver  or  its  support  routines  must  call 
MS-DOS,  the  request  should  be  queued  and  issued  after  the  driver  has  re¬ 
turned.  One  method  for  doing  this  involves  hooking  interrupt  21H  and  execut¬ 
ing  the  DOS  call  immediately  after  MS-DOS  returns  from  the  device  driver. 

Note:  The  binary  interface  cannot  be  called  directly  from  within  the  device 
driver  because  t’  e  interface,  in  turn,  calls  VDI  Management  and  VDI  Man¬ 
agement  must  he  able  to  call  MS-DOS. 


4.3  ASCII  Interface  issues 


ASCII  interface  issues  include  ASCII  text  string  formats,  parameter  value 
formats,  device  driver  buffer  behavior,  device  driver  communications  modes, 
and  using  the  IOCTL  function.  The  following  subsections  cover  these  issues. 


4.3.1  ASCII  string  formats 


Command  strings  are  simply  tokens  separated  by  delimiters.  Return  strings 
consist  of  comma-separated  values.  The  following  subsections  discuss  com¬ 
mand  and  return  strings  formats. 

Command  string  tokens _ 

A  command  string  is  a  series  of  tokens,  separated  by  delimiters,  and  ending 
with  a  CR  Tokens  are  strings  of  one  or  more  printable  characters.  They  in¬ 
clude  command  names,  parameter  identifiers,  and  parameter  values.  Com¬ 
mand  names  and  parameter  identifiers  consist  of  characters  in  the  ranges 
“A"  to  “Z "  and  “a”  to  V.  Case  is  not  significant  For  example,  the  command 
name  “vdPlay”  could  be  supplied  as  ‘vdplay”,  *VDPLAY”,  or  even  “vDpLaY". 
Parameter  values  consist  of  characters  in  the  ranges  “a”  to  “z”,  “A"  to  “Z”,  and 
“0”  to  “9”  plus  “  V,  and 
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Command  string  delimiters _ 

Delimiters  are  the  characters  equals  (ASCII  3DH),  space  (ASCII  20H),  tab 
(ASCII  09H),  LF  (ASCII  OAH)  and  comma  (ASCII  2CH).  Two  ac(jacent  delimi¬ 
ters  are  treated  as  if  they  were  a  single  delimiter.  Extra  delimiters  at  the 
start  or  end  of  the  string  are  ignored. 

Command  string  length _ 

Command  strings  can  be  at  most  255  characters  including  the  CR.  Redun¬ 
dant  delimiters  do  not  count  towards  the  255-character  limit. 

Multiple  commands  separated  by  CRs  may  be  included  in  a  single  string  and 
sent  to  the  ASCII  interface  with  single  write  operation.  The  255-character 
limit  applies  to  each  command  in  the  write  operation,  not  to  the  write  opera¬ 
tion  as  a  whole. 

Response  strings _ 

Response  strings  always  end  with  CR/LF.  If  a  string  contains  multiple  val¬ 
ues,  each  value  is  separated  from  the  next  by  one  comma  with  no  spaces.  Re¬ 
sponse  strings  contain  no  delimiters  before  the  first  value  or  between  the  last 
value  and  CR/LF. 


4.3.2  ASCII  string  formal  syntax 


The  formal  syntax  description  for  ASCII  command  and  response  strings  in 
Table  4—1  uses  a  notation  derived  from  the  Backus  Naur  Form  (BNF).  The 
syntax  uses  the  following  rules. 

1.  Angle  brackets  (o)  enclose  items  that  are  defined  by  the  formal 
descriptions. 

2.  Vertical  bars  ( I )  separate  sets  of  alternatives — in  deriving  a  valid  com¬ 
mand  string,  one  of  the  alternatives  should  be  chosen. 

3.  Square  brackets  ([  ])  enclose  optional  items  or  sets  of  items.  Their  pres¬ 
ence  or  absence  does  not  affect  the  string’s  validity. 

4.  Spaces  separate  sets  of  required  items  that  should  occur  in  the  given  order. 

5.  The  sign  means  “consists  of.”  The  item  on  the  left  of  consists  of 
the  definition  on  the  right. 

6.  The  strings  “equals",  “space”,  “tab”,  “line  feed”,  and  “comma”  are  delimi¬ 
ters  and  stand  for  the  indicated  characters. 

7.  The  string  “carriage  return”  is  a  terminator  and  stands  for  the  indicated 
character. 

8.  Items  in  quotes  (*”)  are  Btring  literals  and  stand  for  themselves. 
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Table  4-1. 
Formal  BNF  syntax 
for  ASCII  command 
and  response  strings 


<command  string> 

:=  [<delimiter  string*]  <command  name>  [<parameter 
string>]  [<delimiter  string>]  carriage  return1 

<response  string> 

:=  “OK"  carriage  return  line  feed  |  “ERROR"  space  digit 
string>  carriage  return  line  feed  |  <result  string> 
carriage  return  line  feed 

<parameter  string> 

:=  <parameter>  |  <parameter>  <parameter  string> 

<parameter> 

:=  delimiter  string>  <parameter  id>  [<delimiter  string> 
<parametervaiue>]1 

<parameter  id> 

=  <letter  string>  [<digit  string>]2 

<command  name> 

=  defter  string*2 

cresult  string> 

=  parameter  value>  |  <parameter  value>  comma 
<result  string> 

<parameter  value> 

=  defter  string>  |  <number>|  dilename* 

<delimiter  string> 

=  delimiter*  |  delimiter*  <delimiter  string>1 

defter  string> 

=  detter>  |  <letter>  defter  string> 

<digrt  string> 

=  digit  string>  |  <digit>  <digit  string> 

<file  name> 

=  degal  file  name  string  for  operating  system> 

<number> 

=  [<sign>]  <digit  string>  |  [<sign>]  [<digit  string>]  “." 
digit  string> 

<delimiter> 

=  equals  |  space  |  tab  |  comma  |  line  feed  | 

<letter> 

»  “A"  |  “B"  |  “C"  |  “D"  |  “E“  |  “F"  |  “G"  |  “H"  |  “1"  |  “J”  |  “K”  | 

“L“  |  “M"  |  “N"  |  “0"  |  “P"  |  “Q"  |“R"  |  “S"  |  T"  |  “U"  |  “V"  |  1 
“W"  |  “X"  |  “Y"  |  “Z"  |  “a"  |  “b"  |  “c"  1  “d"  1  “e"  |  T  |  “g”  |  “h"  1 
|  "i"  11"  |  V  |  “1"  1  “m"  |  “n"  |  “o'  |  “p"  |  “q"  |  V  |  “s"  |  “t"  |  | 

V  |  V  |  "w"  |  “x"  |  Y 1  “z" 

<digit> 

=  “O'  |  “1"  |  “2"  |  “3"  |  “4"  |  “5"  |  “6”  |  “7"  |  “8"  |  “9" 

<sign> 

1  Redundant  delimiters  in  a  delimiter  string>  are  ignored  and  do  not  count 
toward  any  length  limits.  For  a  <command  string>,  redundant  delimiters 

include  all  leading  delimiters,  all  trailing  delimiters  after  the  carriage  return, 
and  any  instance  of  more  than  one  delimiter  in  a  delimiter  string>  between 
the  <command  name>  and  the  carriage  return. 


2This  is  not  a  complete  definition.  The  items  on  the  left  can  take  on  a  limited 
range  of  values  (see  Section  5). 


The  formal  description  above  omits  the  255-character  limit  and  the  equiva¬ 
lency  of  lower  and  upper  case. 
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4.3.3  ASCII  parameter  value  formats 


ASCII  interface  parameter  values  include  numeric  parameters  and  decimal 
integer  representations  of  bit  fields.  Their  formats  are  discussed  below. 


Numbers _ 

Numeric  parameters  include  device  numbers,  mode  numbers,  time  periods, 
and  error  numbers.  These  are  passed  in  decimal  format,  which  is  defined  as: 

•  an  optional  sign  (“+”  or  “-”)  followed  by  a  string  of  decimal  digits  (for 
numbers  without  fractional  parts); 


•  an  optional  sign  (“+”  or  followed  by  an  optional  string  of  decimal  dig¬ 
its  followed  by  followed  by  a  mandatory  string  of  decimal  digits  (for 
numbers  with  fractional  parts); 

Note  that  by  these  definitions  “5”,  “0.5”,  and  “.5”  are  legal  but  “5.”  is  not  (a 
decimal  point  with  no  fractional  part). 


Bit  fields 


A  bit  field  is  represented  as  a  decimal  integer.  The  integer  is  the  sum  of  the 
bit  values  in  the  field. 

For  example,  the  support  value  returned  by  syGetState  is  derived  by  treat¬ 
ing  the  Boolean  supported/not  supported  values  as  elements  in  a  bit  field. 
Table  4-2  lists  the  decimal  numbers  returned  for  the  different  service  groups. 
The  value  of  the  bit  field  is  the  sum  of  the  values  for  each  group.  (Note  that 
the  system  (sy)  group  is  always  present  if  VDI  Management  is  working.) 


Table  4-2. 
ASCII  bit  field  values 


Service  group 

Decimal  value 
returned  by 
syGetState 

System  (sy) 

1 

Visual  management  (vm) 

2 

Videodisc  (vd) 

4 

XY  input  (xy) 

8 

Assume  a  system  supports  vm  and  vd,  but  not  xy  commands.  The  syGetSt¬ 
ate  return  value  is  1  +  2  +  4  or  decimal  7.  If  all  command  groups  are  sup¬ 
ported,  the  return  value  is  15. 
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Text  _ 

Some  return  strings  for  query  parameters  include  values  other  than  num¬ 
bers.  These  strings  consist  of  at  most  upper-case  alpha  characters,  decimal 
digits,  commas,  the  decimal  point,  and  a  sign  (+  or  -). 


4.3.4  Device  driver  buffer  behavior 


The  way  in  which  the  device  driver  buffers  character  strings  must  be  compati¬ 
ble  across  different  versions  of  MS-DOS.  When  the  driver  loads  it  allocates  a 
command  buffer  and  a  response  buffer.  At  start-up,  the  command  buffer  is 
empty  and  the  response  buffer  contains  the  string  “ERROR  19”  (Device 
driver  read  before  write).  If  an  application  tries  to  read  the  driver  before  writ¬ 
ing  to  it,  the  application  reads  this  string.1 

When  the  driver  receives  a  character,  it  adds  it  to  the  command  buffer  and 
checks  to  see  if  it  is  a  CR  If  it  is  not,  the  driver  returns.  If  it  is,  the  driver 
and  VDI  Management  process  the  contents  of  the  command  buffer,  execute 
the  command,  and  generate  a  response  string.  The  response  string  replaces 
any  existing  contents  of  the  response  buffer. 

When  MS-DOS  tries  to  read  a  character  from  the  driver,  the  driver  checks 
the  response  buffer.  If  the  buffer  contains  characters,  the  driver  returns  the 
first  character  and  deletes  it  from  the  buffer.  If  the  buffer  is  empty,  the  driver 
returns  end  of  file  (EOF). 

Some  programming  languages  internally  buffer  device  driver  writes  and  do 
not  furnish  a  way  to  flush  the  buffer  other  than  closing  the  file  to  which  it  is 
attached.  Users  of  such  languages  must  be  able  to  force  a  write  to  the  driver 
without  losing  the  response  to  the  forced  write.  Therefore,  closing  and  reopen¬ 
ing  the  driver  empties  the  command  buffer  but  does  not  change  the  contents 
of  the  response  buffer. 

If  one  application  ends  and  a  new  application  starts,  the  driver  does  not  flush 
the  response  buffer  until  it  receives  a  CR.  Therefore,  an  application  should 
not  read  the  driver  before  writing  at  least  one  command  or  it  may  read  an  in¬ 
valid  response  left  by  the  previous  application. 

If  an  application  writes  a  command  longer  than  255  characters,  the  driver  dis¬ 
cards  the  command  hy  clearing  the  buffer  and  ignoring  additional  characters 
up  to  the  next  CR  The  driver  then  issues  “ERROR  17”  (Command  too  long). 


1 .  Note  that  this  applies  only  to  the  first  time  an  application  accesses  the  driver  after  boot  time.  The  response 
buffer  is  not  automatically  reset  to  “ERROR  19”  after  an  application  exits. 
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4.3.5  Device  driver  IOCTL  and  mode  options _ 

Developers  must  make  several  choices  about  which  functions  to  provide  with 
MS-DOS  device  drivers.  These  include  support  for  IOCTL  functions,  output 
until  busy,  and  generic  IOCTL  commands. 

Although  the  recommended  practices  do  not  require  any  of  these  capabilities, 
the  device  drive  may  furnish  them  and  still  be  compliant.  Fot  example,  a 
driver  might  use  IOCTL  commands  to  switch  between  an  compliant  mode 
and  a  dedicated,  nonportable  mode.  However,  applications  that  use  these  facil¬ 
ities  are  noncompliant  because  the  facilities  are  not  part  of  the  recommended 
practices  and  may  not  be  supported. 

Another  choice  is  whether  device  drivers  should  operate  in  ASCII  (“cooked”) 
or  binary  (“raw”)  mode.2  The  driver  should  work  properly  using  either  mode 
because  applications  may  choose  either  and  be  compliant. 

Application  authors  should  note  that  MS-DOS  interrupt  21H  supports  two 
classes  of  file  functions.  One  class  manipulates  files  with  file  handles;  the 
other  uses  CP/M-compatible  file  control  blocks.  Only  the  read/write  functions 
that  use  handles  work  with  device  drivers. 

This  does  not  mean  that  routines  within  a  programming  system  must  explic¬ 
itly  pass  handles  to  the  application.  However,  the  system  should  not  use  MS- 
DOS  interrupt  21H  functions  OF,  10-17, 1A,  21-24, 27,  and  29H,  which  work 
with  file  control  blocks.  This  is  unlikely  to  be  an  issue  because  using  file  han¬ 
dle  functions  has  been  the  method  of  preference  since  the  introduction  of  MS- 
DOS  2.0. 


4.4  Binary  interface  issues 


Binary  interface  issues  include  establishing  which  interrupt  will  be  used  and 
parameter  value  formats.  The  following  subsections  cover  these  issues. 

4.4.1  Setting  the  software  interrupt _ 


The  binary  interface  software  interrupt  is  a  user  interrupt  in  the  range  60H 
to  66H.  The  default  is  interrupt  60H.  When  VDI  Management  loads,  it  checks 
the  environment  space  for  the  variable  IVINT.  The  variable  value  is  a  two- 


2.  In  cooked  mode,  certain  characters  such  as  control  characters  and  EOF  are  subject  to  MS-DOS  interpreta¬ 
tion;  in  raw  mode,  they  are  not.  A  device  driver  that  is  opened  with  the  MS-DOS  open  handle  function, 

Int  21H  function  3DH,  is  by  default  in  cooked  mode.  However,  an  MS-DOS  IOCTL  function,  Int  21H  func¬ 
tion  44H,  can  force  a  handle  to  raw  mode. 
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character  string  representing  a  value  from  60H  through  66H.  The  variable  is 

set  with  a  command  line  in  the  autoexec.bat  file,  for  example:  • 

set  IVINT-66 

If  the  variable  is  set,  VDI  Management  loads  its  interrupt  handler  at  the 
specified  vector.  If  the  variable  is  not  set,  the  handler  is  loaded  at  vector  60H. 

If  the  variable  value  is  invalid,  VDI  Management  politely  declines  to  execute.  ^ 

When  an  application  starts,  it  also  checks  for  IVINT.  If  the  variable  is  pres¬ 
ent,  the  application  uses  the  specified  software  interrupt.  If  IVINT  is  not 
present,  the  application  uses  the  default.  If  the  variable  value  is  invalid,  the 
application  politely  declines  to  execute. 


4.4.2  Binary  parameter  value  formats 


Binaiy  parameter  values  include  integers,  real  numbers,  bit  fields,  strings, 
pointers,  and  color  arrays.  These  formats  are  discussed  below. 


Integers _ 

Integer  quantities  are  passed  as  32-bit,  2’s  complement,  signed  numbers,  in 
the  range  -2,147,483,648  to  +2,147,483,647.  This  is  consistent  with  most  high- 
level  programming  languages.  Examples  of  integers  include  device  numbers, 
graphics  mode  numbers,  and  error  numbers. 


Real  numbers 


Real  numbers  are  passed  by  multiplying  the  real  number  by  65,536,  rounding 
towards  negative  infinity,  and  using  the  integer  part  expressed  in  hexadeci¬ 
mal  with  2’s  complement  Four  bytes  can  represent  fractional  numbers  in  the 
range  -32768  (80000000H)  to  +32767.99998  (7FFFFFFFH)  with  an  accuracy 
of  ±1/65536  (±0.000015). 


In  this  notation,  the  most  significant  16  bits  represent  the  integer  part  of  the 
number  in  2’s  complement.  The  least  significant  16  bits  represent  a  positive 
binary  fraction  to  be  added  to  that  integer.  For  example,  to  represent  -VS,  set 
the  most  significant  16  bits  to  FFFFH  or  -1  decimal  and  the  least  significant 
16  bits  to  8000H  or  +VS  decimal. 

Normal  2’s  complement  addition  and  subtraction  still  yields  correct  results. 
For  example: 

FFFF8000  (-VS)  +  FFFF4000  (-*4)  -  FFFECOOO  (-H/4) 

FFFF4000  (-*4)  +  00020000  (+2)  -  00014000  (1 1/4) 

00001999  (0.1)  +  00003333  (0.2)  -  00004CCC  (0.299988) 
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Bit  fields _ 

Bit  fields  are  best  viewed  as  32  individual  bits  that  can  each  take  a  value  of  0 
or  1.  Specific  bits  in  a  field  correspond  to  specific  items  of  information  that 
can  have  only  two  states,  on  or  off,  true  or  false,  or  present  or  absent. 

Table  4-3  lists  bits  in  the  bit  field  returned  by  syGetState.  This  function 
sets  bits  according  to  which  service  groups  are  present  in  a  VDI  Management 
installation.  (Note  that  the  system  (sy)  group  is  always  present  if  VDI  Man¬ 
agement  is  working.) 


Table  4-3. 
Binary  bit  field 
values 


Service  group 

Least  significant  byte  value  is  group  If  present  | 

Binary 

Hexadecimal 

System  (sy) 

00000001 

01 

Visual  management  (vm) 

00000010 

02 

Videodisc  (vd) 

00000100 

04 

XY  input  (xy) 

00001000 

08 

For  example,  if  the  VDI  implementation  supports  vm  and  vd  commands,  but 
not  xy,  the  least  significant  byte  returned  by  syGetState  is  00000111B  or 
07H.  (See  Appendix  C  for  a  code  fragment  showing  how  to  analyze  bit  fields.) 


Strings _ 

Strings  returned  via  the  binary  interface  are  passed  by  reference.  The  return 
value  is  a  pointer  to  an  ASCII  string  of  up  to  255  printable  characters  fol¬ 
lowed  by  a  null  character  (00H).  Alphabetical  characters  in  the  return  string 
are  upper  case.  The  most  significant  16  bits  of  the  pointer  contain  the  string's 
segment  address;  the  least  significant  16  bits  contain  the  offset  within  the 
segment. 


VDI  Management  allocates  memory  to  hold  return  strings.  An  application  should 
not  change  this  memory  even  though  it  knows  the  string’s  address  or  dire 
consequences  may  result. 


Color  arrays _ 

The  vmGetPalette  and  vmSetPalette  commands  use  arrays  containing  pal¬ 
ette  information.  These  arrays  are  passed  by  reference.  The  parameter 
packet  contains  three  parameters,  a  logical  color  parameter,  a  length  parame¬ 
ter,  and  a  array  address  parameter. 
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The  array  parameter  value  is  a  long  pointer  to  a  memory  block  containing  an 
array  of  palette  colors.  Each  palette  color  value  is  a  32-bit  structure  contain¬ 
ing  four  1-byte  values: 

•  Byte  0,  the  least  significant  byte,  represents  BQue); 

•  Byte  1  represents  GKreen); 

•  Byte  2  represents  R(ed);  and 

•  Byte  3,  the  most  significant  byte  is  reserved  and  is  set  to  zero. 

The  reserved  byte  must  be  set  to  zero — VDI  Management  returns  error  51 
(Parameter  value  invalid  or  out  of  range)  if  it  is  not. 

The  length  parameter  is  the  number  of  32-bit  structures  in  the  color  array. 
The  color  parameter  is  the  logical  color  number  to  which  the  first  palette 
color  structure  is  assigned.  The  second  palette  color  structure  is  assigned  to 
the  next  contiguous  logical-color  number;  the  third  structure  to  the  third  logi¬ 
cal  color;  and  so  on  up  to  length  logical  colors. 

Assume  a  parameter  packet  contains  logical  color  =  4,  length  =  3,  and 
array  =  3000:0820.  The  array  memory  block  is  interpreted  as: 

3000 :0820  32-bit  word  for  logical  color  4 
3000:0824  32-bit  word  for  logical  color  5 
3000 :0828  32-bit  word  for  logical  color  6 

The  pointer  format  is  the  same  as  that  for  a  string— the  most  significant  16 
bits  contain  the  segment  address  and  the  least  significant  16  bits  contain  the 
offset  within  that  segment. 
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This  section  includes  summary  tables  of  the  commands  and  parameters  for 
both  the  ASCII  and  binary  interfaces  with  token  numbers  for  the  binary 
interface.  See  Section  3  for  detailed  information  on  how  to  use  the  interfaces 
and  Sections  4.3  and  4.4  for  information  on  ASCII  string  syntax  and  ASCII 
and  binary  parameter  value  formats.  Appendixes  C  and  D  provide  program¬ 
ming  examples  and  cover  error  handling,  respectively. 


5.1  Command  names  and  token  numbers 


The  binaiy  interface  uses  token  numbers  instead  of  command  names.  These 
numbers  map  directly  to  ASCII  command  equivalents  in  terms  of  definition 
and  functionality.  To  assign  binary  token  numbers,  each  ASCII  command 
name  is  first  divided  into  a  service  group  prefix,  such  as  sy  or  vm,  and  a  com¬ 
mand  word,  such  as  GetState  or  Init. 


Table  5-1  lists  the  prefix  value  of  each  service  group.  As  the  table  shows, 
service-group  prefixes  have  values  that  are  multiples  of  1024  (0400H).  This 
has  the  advantages  of  leaving  room  for  logically  grouping  additional  com¬ 
mands  as  the  recommendations  evolve  and  allowing  the  determination  of 
which  service  group  an  token  number  is  in  with  a  single  shift  right  and  com¬ 
pare  operation. 


Table  5-1. 
Service  group  prefix 
values  for  the  binary 
interface. 


Service  group  prefix 

Value 

(decimal) 

Value 

(hexadecimal) 

sy 

1024 

0400 

vm 

2048 

0800 

vd 

3072 

ocoo 

xy 

4096 

1000 
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Table  5-2  lists  the  value  for  each  command  word.  Commands  words  are  num¬ 
bered  1-20  in  alphabetical  order.  However,  because  the  numbers  must  be 
“cast  in  stone”  for  backwards  compatibility,  new  words  will  be  appended  to 
the  list  and  the  correspondence  of  alphabetical  order  to  numeric  order  will 
not  be  maintained  as  the  recommended  practices  evolve.  This  approach  offers 
the  advantages  of  the  ability  to  determine  the  command  word  by  simply  sub¬ 
tracting  the  service  group  value  and  looking  up  the  word  and  the  increased 
efficiency  of  contiguous  numbers  in  a  lookup  table. 


Table  5-2. 
Command  word 
values  for  the  binary 
interface 


ASCII  name 

Value 

Value 

(decimal) 

(hexadecimal) 

CheckError 

1 

01 

ErrorMsg 

2 

02 

Fade 

3 

03 

Getlnput 

4 

04 

GetPalette 

5 

05 

GetState 

6 

06 

jlnit 

7 

07 

PassThru 

8 

08 

Play 

9 

09 

Queue 

10 

0A 

Scan 

11 

0B 

Search 

12 

OC 

Set 

13 

0D 

SetGraphics 

14 

0E 

SetPalette 

15 

OF 

SetTrans 

16 

10 

SetVideo 

17 

11 

Step 

18 

12 

|  Still 

19 

13 

[stop 

20 

14 

Table  5-3  lists  ASCII  commands  and  their  equivalent  binaiy  token  numbers 
organized  by  service  group.  Each  token  number  is  the  sum  of  the  service- 
group  prefix  value  and  the  command  word  value.  For  some  commands,  this 
offers  the  advantage  of  deriving  token  numbers  from  different  prefixes  that 
use  the  same  command  word.  For  example,  in  C  a  series  of  #define  state¬ 
ments  might  include: 

#define  SY 1024 
#define  VM  2048 
#define  INIT7 
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Then,  the  token  number  for  sylnit  could  be  derived  with: 

SY  +  INIT 

The  table  also  indicates  whether  the  commands  are  core  or  extended.  Core 
commands  must  be  implemented  for  a  given  service  group  to  be  compliant. 
Extended  commands  are  optional  and  should  be  considered  nonportable  un¬ 
less  an  application  is  written  to  use  them  if  present  and  handle  their  absence. 


Table  5-3. 
A  summary  of 
command  names 
including  binary 
token  numbers  and 
types 


ASCII  name 

Token  number 
(decimal) 

Token  number 
(hexadecimal) 

Type 

1  sy  service  group  | 

syCheckError 

1025 

0401 

Core 

syErrorMsg 

1026 

0402 

Extended 

syGetState 

1030 

0406 

Core 

sylnit 

1031 

0407 

Core 

syQueue 

1034 

040A 

Core 

syStop 

1044 

0414 

Core 

1  vm  service  group  | 

llvmFade 

2051 

0803 

Core 

ivmGet  Palette 

2053 

0805 

Core 

SvmGetState 

2054 

0806 

Core 

jvmlnit 

2055 

0807 

Core 

IvmSetGraphics 

2062 

080E 

Core 

IvmSetPalette 

2063 

080F 

Core 

ivmSetTrans 

2064 

0810 

Core 

IvmSetVideo 

2065 

0811 

Core 

f  vd  service  group  [ 

JvdGetState 

3078 

0C06 

Core 

Jvdlnit 

3079 

0C07 

Core 

IvdPassThru 

3080 

0C08 

Core 

IvdPlay 

3081 

0C09 

Core 

vdScan 

3083 

0C0B 

Core 

vdSearch 

3084 

ococ 

Core 

vdSet 

3085 

0C0D 

Core 

vdStep 

3090 

0C12 

Core 

vdStill 

3091 

0C13 

Core 

I  xy  service  group  | 

xyGetlnput 

4100 

1004 

Core 

xyGetState 

4102 

1006 

Core 

xylnit 

4103 

1007 

Core 

xySet 

4109 

100D 

Core 

April  15, 1990 


Release  R  1.0 


5-3 


Recommended  Practices  for  Interactive  Video  Portability 


5.2  Parameter  names  and  token  numbers 


Parameter  numbers  are  contiguous  starting  with  one.  The  majority  of  param¬ 
eter  token  numbers  map  to  ASCII  parameter  names.  However,  some  binary 
parameter  numbers  such  as  array  and  length  have  no  ASCII  equivalents. 

Table  5—4  lists  parameter  names  and  their  binary  token  numbers.  Parame¬ 
ters  are  numbered  1-67  in  alphabetical  order.  However,  because  the  numbers 
must  be  “cast  in  stone"  for  backwards  compatibility,  new  parameters  will  be 
appended  to  the  list  and  the  correspondence  of  alphabetical  order  to  numeric 
order  will  not  be  maintained  as  the  recommended  practices  evolve. 

The  table  also  indicates  whether  the  parameters  are  core  or  extended.  Core 
parameters  for  a  given  service  group  must  be  implemented  for  compliance. 
Extended  parameters  are  optional  and  should  be  considered  nonportable  un¬ 
less  an  application  is  written  to  use  them  if  present  and  handle  their  absence. 
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Table  5-4. 
A  summary  of 
parameter  labels 
including  binary 
token  numbers 


Parameter 

name 

Token 

number 

(decimal) 

Token 

number 

(hex) 

Parameter 

name 

Token 

number 

(decimal) 

Token 

number 

(hex) 

array 

1 

01 

motion 

35 

23 

audiol 

2 

02 

physcolors 

36 

24 

audio2 

3 

03 

pmsg 

37 

25 

b 

4 

04 

r 

38 

26 

buttons 

5 

05 

remote2 

39 

27 

edisplay 

6 

06 

speed 

40 

28 

chapter 

7 

07 

spin 

41 

29  | 

clear 

8 

08 

state 

42 

2A  I 

color 

9 

09 

support 

43 

2B 

command 

10 

0A 

tbuttons 

44 

2C 

cursor1 

11 

0B 

tdevices 

45 

2D 

defdevice 

12 

OC 

t  sources 

46 

2E  | 

defsource 

13 

0D 

time 

47 

2F  | 

device 

14 

0E 

to 

48 

30 

direction 

15 

OF 

transcolors 

49 

31 

disetype 

16 

10 

vertpi> 

50 

32 

dlevel 

17 

11 

video 

51 

33 

door2 

18 

12 

vlevel 

52 

34 

|  emulation 

19 

13 

vmode 

53 

35 

|  enable 

20 

14 

wait 

54 

36 

Dermo 

21 

15 

width3 

55 

37 

|  execute 

22 

16 

xmax 

56 

38 

frame 

23 

17 

xmaxciip 

57 

39 

from 

24 

18 

xmin 

58 

3A 

9 

25 

19 

xminciip 

59 

3B 

glevel 

26 

1A 

xoffset 

60 

3C 

gmode 

27 

IB 

xpos 

61 

3D 

horzpix 

28 

1C 

ymax 

62 

3E 

idxdsiplay 

29 

ID 

ymaxdip 

63 

3F  | 

iwer 

30 

IE 

vmin 

64 

40 

length 

31 

IF 

yminclip 

65 

41 

logcolors 

32 

20 

yoffset 

66 

42 

mfgname 

33 

21 

ypos 

67 

43 

mfgver 

34 

22 

Mill 

1  Currently  used  only  as  an  extended  parameter  in  the  xy  service  group. 
Currently  used  only  as  an  extended  parameter  in  the  vd  service  group. 
Currently  used  only  as  an  extended  parameter  in  the  vm  service  group. 
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6  System  commands  (sy) 


This  section  describes  commands  that  relate  to  overall  VDI  software  opera¬ 
tion.  These  commands  initialize  the  basic  IV  system  (but  not  other  service 
groups);  obtain  specific  information  about  system  software  and  its  configura¬ 
tion;  retrieve  error  information;  queue  commands  for  subsequent  execution; 
and  free  resources  when  the  VDI  software  is  not  in  use.  Table  6-1  lists  the 
commands  covered  in  this  section,  their  token  numbers,  and  their  types. 


Table  6-1. 
System  command 
names,  token 
numbers,  and  types 


1  Upper  or  tower  case  for  command  names  is  not  significant. 

Compliant  implementations  must  support  “Core”  commands.  Supporting 
"Extended”  commands  is  optional,  and  these  commands  should  be  considered 
nonportable  unless  properly  handled  when  absent. 


ASCII  command 
name1 

Binary  Interface 
token  number 
(decimal) 

Type2 

syCheckError 

1025 

Core 

syErrorMsg 

1026 

Extended 

syGetState 

1030 

Core 

sylnit 

1031 

Core 

syQueue 

1034 

Core 

syStop 

1044 

Core 
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syCheckError 


Last  revision:  R  1.0 
Type:  core 


Parameters 


ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

command 

Core 

None 

N/A 

Command  name 
that  caused  error 

Text 

No  action 

errno 

Core 

None 

N/A 

Last  detected 
error  number 

Integer 

No  action 

|  At  least  one  parameter  is  required  or  an  error  is  returned.  | 

Binary 

Command  code:  1025  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If 
parameter 
not  used 

command 

Core 

10 

Integer 

Any  value 

Command  token 
that  caused  error 

No  action 

errno 

Core 

21 

Integer 

Any  value 

Last  detected 
error  number 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


Description 

Summary  syCheckError  returns  the  number  of  the  last  error  detected  by  VDI  Man¬ 

agement,  if  present,  and  the  command  that  caused  the  error.  syCheckError 
then  clears  this  error  information. 


General  VDI  Management  may  detect  errors  that  do  not  occur  in  immediate  response 

discussion  to  application  commands.  Such  errors  may  occur,  for  example,  after  player 

motion  commands,  fade  and  dissolve  commands,  queued  commands,  and  oth¬ 
ers  that  execute  over  time  after  being  accepted.  syCheckError  is  provided 
to  detect  these  types  of  errors,  although  it  will  return  the  last  error  regard¬ 
less  of  the  error’s  cause. 
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Implementation 

notes 


Command 

parameter 


syCheckError 

Assume  a  player  accepts  a  valid  vdPlay  command  without  a  wait  modifier 
(see  Section  8).  VDI  Management  will  return  success  immediately  (“OK”  for 
the  ASCII  interface,  AX  =0  for  the  binary  interface).  If  the  player  then  fails 
during  the  specified  motion  sequence,  an  error  state  exists.  syCheckError 
determines  if  such  a  situation  has  arisen  and,  if  so,  returns  the  error.  Simi¬ 
larly,  if  a  fade  is  successfully  initiated  and  subsequently  fails,  an  unreported 
error  results.  Finally,  a  queued  command  may  result  in  an  error  although 
syQueue  execute  was  successful.  syCheckError  returns  the  error  result¬ 
ing  from  the  queued  command.  However,  the  return  does  not  specify  which 
queued  command  generated  the  error. 

While  actual  implementations  may  vary  in  the  way  they  store  and  translate 
the  information  needed  by  syCheckError,  in  concept  VDI  Management 
maintains  three  buffers  for  returning  error  information,  the  response  buffer, 
the  check  error  buffer,  and  the  check  command  buffer.  The  contents  of  these 
buffers  (or  the  translations  thereof)  depends  on  which  interface  is  used. 

For  the  ASCII  interface: 

•  the  response  buffer  contains  the  return  string  for  the  most  recent  com¬ 
mand,  either  “ERROR  n...”  where  “n...”  is  an  error  number,  “OK”,  or  re¬ 
quested  information; 

•  the  check  error  buffer  contains  the  error  number  as  “n...”  of  the  most  re¬ 
cent  error  caused  by  any  command  or  “0”  if  no  error  has  occurred  or  the 
buffer  has  been  cleared;  and 

•  the  check  command  buffer  contains  the  name  of  the  command  that 
caused  the  error  or  “OK"  if  no  error  has  occurred  or  the  buffer  has  been 
cleared. 

For  the  binaiy  interface: 

•  the  response  buffer  contains  the  value  to  be  returned  in  the  AX  register 
for  the  most  recent  command,  either  an  error  number  or  zero  if  no  error 
occurred; 

•  the  check  error  buffer  contains  the  error  number  of  the  most  recent 
error  caused  by  any  command  or  zero  if  no  error  has  occurred  or  the 
buffer  has  been  cleared;  and 

•  the  check  command  buffer  contains  the  token  number  of  the  command 
that  caused  the  error  or  zero  if  no  error  has  occurred  or  the  buffer  has 
been  cleared. 

The  command  parameter  requests  the  command  that  caused  the  last  error, 
if  present.  Issuing  syCheckError  with  command  clears  the  error  number 
in  the  check  number  buffer  as  well  as  the  command  name  or  token  in  the 
check  command  buffer. 
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syCheckError 

• 

Errno  parameter 

The  errno  parameter  requests  the  error  number  of  the  last  error  detected.  Is¬ 
suing  syCheckError  with  errno  clears  the  command  name  or  token  in  the 
check  command  buffer  as  well  as  the  error  number  in  the  check  number 
buffer. 

+ 

Notes 

1.  syCheckError  does  not  queue  errors.  For  example,  if  a  player  motion  com¬ 
mand  resulting  in  an  unreported  error  is  followed  by  a  fade  command  re¬ 
sulting  in  an  unreported  error,  the  unreported  error  for  the  player  motion 
command  is  lost. 

2.  Only  syCheckError  and  sylnit  can  clear  the  check  error  and  check  com¬ 
mand  buffers.  However,  sylnit  also  reinitializes  VDI  Management,  clear¬ 
ing  the  queue,  canceling  any  pending  commands,  and  setting  up 
interrupts.  Therefore,  it  should  not  be  used  simply  to  clear  an  error  state. 

3.  If  syCheckError  itself  causes  an  error  because,  for  example,  it  is  issued 
with  an  invalid  parameter,  it  does  not  clear  the  check  buffers.  Instead, 

VDI  Management  loads  the  check  error  and  check  command  buffers  with 
the  same  information  it  would  load  for  any  other  command  causing  an 
error.  A  subsequent  correct  call  to  syCheckError  returns  and  clears  this 
information. 

• 

4.  Trying  to  queue  syCheckError  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 

• 

Returns 

ASCII 

On  success:  For  errno  parameter,  last  error  number  as  “n...”  or  “0”  if  no 
error.  For  command  parameter,  name  of  command  causing  last  error  as  an 
upper-case  alpha  string  or  “OK"  if  no  error. 

• 

On  failure:  “ERROR  n...". 

• 

Binary 

On  success:  AX  =  0.  Value  associated  with  the  errno  parameter  is  the  last 
error  number  as  a  32-bit  integer  or  0  if  no  error.  Value  associated  with  the 
command  parameter  is  the  token  number  of  the  command  that  caused  the 
error  or  0  if  no  error. 

• 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 

See  also: 

syErrorMsg,  sylnit,  syQueue. 

• 
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syCheckError 


Examples 

ASCII 


Passnon- 
syCheckError 
command  that 
causes  an  error 

syErrorMsg  ermo 
(returns)  “ERROR  53” 

;  Missing  parameter  value 

Now  query  for  last 
error  and  related 
command 

syCheckError  ermo,  command 

(returns)  “53, SYERRORMSG”  ;  clears  all  last  error  information 

Requery  after 
clearing 

syCheckError  ermo,  command 
(returns)  “0,OK” 

Binary 

Query  for  last 
error  and  related 
command  token 

AX  1025 

BX  1 

ES.DItO]  21 

ES:DI[4]  any  value 
ES:DI[8]  10 

ES:DI[C]  any  value 

syCheckError  decimal  ID 

number  of  parameters  (required  for  return) 

emo  decimal  ID 

place  holder  for  value  on  return 

command  decimal  ID 

place  holder  for  value  on  return 

After  return 

AX  0 

ES:DI[4]  error  no. 

ES:DI[C]  token  no. 

returns  0  if  successful  (nonzero  if  not) 
number  of  most  recent  error,  if  present 
(zero  if  no  error,  undefined  if  AX*0) 
token  number  of  command  causing  error 

(zero  if  no  error,  undefined  if  AX*0) 
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SyErrorMsg  Last  revision:  R  1 .0 

Type:  extended 


Parameters 

ASCII 


Parameter 

Core  or 

Associated  calling 

Type 

Associated  return 

Type 

Default  if 

extended 

value 

as 

ASCII 

value 

as 

ASCII 

parameter 
not  used 

errno 

Core 

Error  number 

Integer 

Error  description 
string 

Text 

Causes 

error 

Ermo  must  be  specified  or  an  error  is  returned. 


Binary 

Command  code:  1026  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  H 
parameter 
not  used 

errno 

Core 

21 

Integer 

Error  number 

None 

Causes 

error 

pmsg 

Core 

37 

Pointer 

Any  value 

Pointer  to  error 
description  string 

Causes 

error 

|Both  parameters  must  be  specified  or  an  error  is  returned. 

Description 


Summary 


syErrorMsg  returns  an  ASCII  string  of  up  to  255  characters  that  describes 
the  specified  error  number. 


General 

discussion 


When  an  ASCII  interface  command  causes  an  error,  the  error  is  reported  as 
“ERROR  n...”  where  “n...”  is  the  error  number  expressed  in  ASCII  digits.  The 
binary  interface  returns  the  error  number  in  the  AX  register.  Applications 
can  use  the  error  number  with  syErrorMsg  to  request  a  description.  VDI 
Management  developers  may  opt  to  keep  error  descriptions  in  memory  or  a 
separate  file. 


Eirno  parameter  The  errno  parameter  specifies  the  error  number  for  which  a  descriptive 
string  will  be  returned. 

Pmsg  parameter  The  pmsg  parameter  for  the  binary  interface  has  an  associated  return  value 

that  points  to  the  location  of  the  descriptive  string. 
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syErrorMsg 


Notes  1.  Appendix  D  lists  strings  for  specific  error  numbers. 

2.  Trying  to  queue  syErrorMsg  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 

Returns 

ASCII  On  success:  Error  description  string. 

On  failure:  “ERROR  n. 

Binary  On  success:  AX  =  0.  Value  associated  with  the  pmsg  parameter  is  a  32-bit 

pointer  to  a  null-terminated  error  description  string. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


See  also:  syCheckError,  syQueue. 


Examples 

ASCII 

Pass  an  Invalid  syErrorMsg  error=55 

parameter  (returns)  “ERROR  48” 

Get  string  syErrorMsg  ermo=48 

describing  error  48  (returns)  “UNKNOWN  PARAMETER” 

Pass  Insufficient  syErrorMsg 

parameters  (returns)  “ERROR  49” 

Get  string  syErrorMsg  ermo=49 

describing  error  49  (returns)  “INSUFFICIENT  PARAMETERS” 


Binary 


Get  string 

AX 

1026 

;  syErrorMsg  decimal  ID 

describing 

BX 

2 

;  number  of  packets 

error  176 

ES:DI[0] 

21 

;  errno  decimal  ID 

ES:DI[4] 

176 

;  decimal  error  number 

ES:DI[8] 

37 

;  pmsg  decimal  ID 

ES.DIfC] 

any  value 

;  place  holder  for  value  on  return 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

ES:DI[C] 

pointer 

;  pointer  to  message  string 
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syGetState 


Last  revision:  R 1 .0 
Type:  core 


Parameters 

ASCII 


j  Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

iwer 

Core 

None 

N/A 

Recommended 
practices  version 
number 

Real 

No  action 

mfgname 

Core 

None 

N/A 

Text 

No  action 

mfgver 

Core 

None 

N/A 

E2B 

No  action 

support 

Core 

None 

N/A 

Value  of  bit  field 
for  installed 
service  groups 

Integer 

No  action 

|  At  least  one  parameter 

is  required  or  an  error  is  returned.  ( 

1  Eight  characters  ma  Restricted  to  printable  characters  and  cannot  include  white 
space  (ASCII  20H,  C9H),  backspace  (ASCII  08H),  a  comma  (ASCII  2CH),  CR  (ASCII 
ODH),  or  LF  (ASCII  OAH). 


Binary 

Command  code:  1030  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If  I 
parameter 
not  used 

iwer 

Core 

30 

Real 

Any  value 

Recommended 
practices  version 
number 

No  action 

mfgname 

Core 

33 

Pointer 

Any  value 

Pointer  to  MFG 
name  string1 

No  action 

mfgver 

Core 

34 

Pointer 

Any  value 

Pointer  to  MFG 
version  string1 

No  action 

support 

Core 

43 

Bit 

field 

Any  value 

Bit  field  of 
installed  service 
groups 

No  action 

J  At  least  one  parameter 

s  required  or  an  error  is  returned.  j 

1  Eight  characters  max.  Restricted  to  printable  characters  and  cannot  include  white 
space  (ASCII  20H,  09H),  backspace  (ASCII  08H),  a  comma  (ASCII  2CH),  CR  (ASCII 
ODH),  or  LF  (ASCII  OAH). 
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Description 

Summary 


Iwer  parameter 


Mfgname  and 

mfgver 

parameters 


Support 

parameter 


syGetState 


syGetState  returns  supported  service  groups  for  which  VDI  Management 
was  configured  at  installation,  the  version  of  the  recommended  practices  sup¬ 
ported,  and  manufacturer  name  and  version  information. 


The  iwer  parameter  returns  the  version  number  of  the  recommended  prac¬ 
tices  with  which  the  VDI  Management  software  complies.  IV  applications  can 
use  this  number  to  determine  compatibility  with  VDI  Management  im¬ 
plementations.  An  application  that  requires  a  given  version  number  will  also 
be  compatible  with  any  higher  version  number. 


The  mfgname  and  mfgver  parameters  return  the  VDI  Management 
manufacturer’s  name  and  software  version  number  respectively.  This  infor¬ 
mation  is  required  to  confirm  compliance  with  the  recommendations  and  for 
software  maintenance  purposes  to  obtain  the  manufacturer  and  version  num¬ 
ber  for  technical  support  An  application  may  also  use  this  information  to  de¬ 
termine  if  a  particular  implementation  that  provides  extended  commands  is 
present. 


The  mfgname  and  mfgver  return  strings  are  eight-character  strings  of 
printable  characters.  The  strings  cannot  include  white  space  (ASCII  20H, 
09H),  backspace  (ASCII  08H),  a  comma  (ASCII  2CH),  CR  (ASCII  ODH),  or 
LF  (ASCII  OAH). 


The  support  parameter  returns  a  bit  field  or  an  ASCII  representation 
thereof  that  specifies  service  groups  that  are  supported  and  for  which  VDI 
Management  was  configured  during  software  installation.  An  application 
should  typically  issue  syGetState  support  immediately  after  sylnit  to  find 
out  if  software  support  exists  for  required  service  groups.  Typically,  an  appli¬ 
cation  will  then  issue  the  specific  xxlnit  command  for  each  represented  ser¬ 
vice  group  that  the  application  will  use.  The  xxlnit  commands  for  individual 
service  groups  initialize  software  support  for  devices  within  the  group  and 
verify  communications  with  the  requisite  hardware. 


The  following  table  shows  return  values  for  each  service  group  after  an 
syGetState  support.  The  actual  value  returned  is  the  sum  of  the  listed  val¬ 
ues  for  all  installed  service  groups.  For  example,  a  binary  status  return  of 
00000111B  means  that  system,  visual  management,  and  videodisc  are  sup¬ 
ported,  but  XY  input  is  not  An  ASCII  return  value  of  “7”  means  the  same. 
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syGetState 


Service  Group 

Binary  interface 
return  value 
(low  byte) 

ASCII  interface 
return  value 

System  (sy) 

00000001 

1 

Visual  management  (vm) 

00000010 

2 

Videodisc  (vd) 

00000100 

4 

XY  input  (xy) 

00001000 

Parameters  If  a  parameter  causes  an  error,  syGetState  returns  immediately  with  an 

resulting  In  errors  error  message.  The  command  does  not  return  partial  responses  for  other 
parameters  that  do  not  cause  errors. 


Notes  1.  Values  for  mfgname  and  mfgver  are  not  under  the  control  of  the  recom¬ 

mended  practices.  (In  the  future,  mfgname  may  be  required  to  be  unique 
and  registered.) 

2.  Trying  to  queue  syGetState  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 


Returns 

ASCII  On  success:  Comma-separated  string  with  response  for  each  specified  pa¬ 

rameter  as  described  above. 

On  failure:  “ERROR  n...”. 

Binary  On  success:  AX  =  0.  Value  associated  with  support  parameter  is  a  32-bit 

bit  field  as  described  above.  Value  associated  with  iwer  is  a  32-bit  real. 
Values  associated  with  mfgname  and  mfgver  parameters  are  pointers  to 
null-terminated  strings  as  described  above. 


On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


See  also:  syQueue,  vdGetState,  vdlnit,  vmGetState,  vmlnit,  xyGetState,  xylnit 
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syGetState 


Examples 


ASCII 


Get  services 
supported  by  in¬ 
stalled  system 

Get  version 
number  of  recom¬ 
mendations 


syGetstate  support 
(returns)  “15” 


syGetstate  iwer 
(returns)  “1.0” 


;  system,  visual  management,  videodisc,  and  XY 
;  commands  supported 


;  conforms  with  recommended  practices 
;  standard,  version  1.0 


Get  manufacturer  syGetstate  mfgname.mfgver 

and  version  (returns)  “IVMAKER.1.3”  ;  VDI  Management  written  by  IVMAKER, 

;  version  1.3 


Binary 


Get  services 

AX 

1030 

supported  by 

BX 

1 

Installed  system 

ES:DI[0] 

ES:DI[4] 

43 

any  value 

After  return 

AX 

ES:DI[4] 

0 

bit  field 

;  gyGetState  decimal  ID 
;  number  of  packets 
;  support  decimal  ID 
;  no  associated  value 

;  returns  0  if  successful  (nonzero  if  not) 
;  support  parameter  bit  field 
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sylnit 

Parameters 

ASCII 

Binary 

Command  code: 

Description 

Summary 

General 

discussion 


Notes 


Last  revision:  R  1 .0 
Type:  core 


No  parameters. 


1031  decimal. 
No  parameters. 


sylnit  initializes  VDI  Management  and  the  sy  service  group  and  confirms 
communications  between  VDI  Management  and  the  application. 


The  specific  actions  taken  by  sylnit  are  highly  implementation  dependent. 
However,  regardless  of  the  implementation,  sylnit  does  the  minimum  re¬ 
quired  to  prepare  the  system  for  other  VDI  Management  commands.  It  does 
not  replace  the  initialization  commands  for  other  service  groups.  For  exam¬ 
ple,  sylnit  does  not  verify  communications  with  a  videodisc  player  or  change 
the  video  display.  However,  it  may  need  to  attach  proper  interrupts  to  proper 
ports,  set  proper  software  interrupts,  disable  non-IV  operating  modes,  and  do 
other  basic  start-up  chores,  sylnit  also  does  the  following  specific  initializa¬ 
tion  tasks: 

•  Sets  the  default  logical  device  or  logical  source  for  all  service  groups  to 
zero. 

•  Clears  the  error  buffers  used  by  syCheckError. 

•  Issues  syQueue  clear ,state*0  to  clear  the  command  queue  and  turn  it 
off. 


1.  Application  programs  should  make  no  assumptions  about  the  state  of  the 
IV  system  or  the  presence  of  service  groups  after  sylnit.  To  determine 
which  service  groups  are  present  and  enable  the  groups,  an  application 
should: 

a.  Issue  sylnit. 

b.  Issue  syGetState  support  to  determine  which  services  are  present. 

c.  Issue  the  initialization  commands  for  the  service  groups  to  be  used  by  the 
application. 
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sylnit 

d.  If  required,  initialize  non-IV  devices  and  allocate  additional  memory.  (At 
the  developer’s  discretion,  these  tasks  may  be  dene  either  before  or  after 
issuing  sylnit  and  other  IV  initialization  commands.) 

2.  Because  the  specific  actions  taken  by  sylnit  are  implementation  dependent 
and  affect  the  state  of  VDI  Management,  if  an  application  reissues  sylnit 
after  the  start-up  sequence  given  above,  it  should  also  repeat  steps  c  and  d 
above  to  ensure  that  the  system  is  in  a  known  state. 

3.  Trying  to  queue  sylnit  causes  error  177  (Command  cannot  be  queued)  at 
the  time  of  the  attempt. 


Returns 

ASCII  On  success:  “OK”. 

On  failure:  “ERROR  n...". 
Binary  On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


See  alSO :  syCheckError,  syGetState,  syQueue,  vdlnit,  vmlnit,  xylnit. 


Examples 


ASCII 

Initialize  VDI  sylnit 

Management  (returns)  “OK” 


Binary 

Initialize  VDI 

AX 

1031 

;  sylnit  decimal  ID 

Management 

BX 

0 

;  no  parameters 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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syQueue 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  If 
parameter 
not  used 

clear 

Core 

None 

N/A 

None 

N/A 

No  action 

execute 

Core 

None 

N/A 

None 

N/A 

No  action 

state 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


Binary 

Command  code:  1034  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  it 
parameter 
not  used 

clear 

Core 

8 

N/A 

Any  value 

None 

No  action 

execute 

Core 

c2 

N/A 

Any  value 

None 

No  action 

state 

Core 

L42 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


Description 

Summary  syQueue  manages  a  fixed-length  internal  queue  with  exactly  10  slots  for  stor¬ 

ing  at  most  10  commands.  The  queue  can  be  turned  on  and  off,  cleared,  and 
executed. 


General  syQueue  stores  commands  in  an  internal  queue  for  later  execution.  It  may 

discussion  be  used  to  collect  commands  that  have  critical  timing  requirements  and 

should  be  executed  together.  One  example  is  a  set  of  changes  that  should 
occur  during  a  vertical  blanking  interval  to  avoid  screen  disturbances,  such 
as  changing  the  palette  and  setting  a  transparent  color.  Queued  commands 
are  always  executed  in  the  order  in  which  they  were  queued  and,  if  possible, 
adjacent  commands  are  executed  in  the  same  vertical  interval. 
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Clear  parameter 


Execute 

parameter 


State  parameter 


Combining 

parameters 


syQueue 


The  clear  parameter  dears  the  queue  of  all  commands  without  executing 
them.  Clear  does  not  change  the  queue’s  state  (on  or  off).  If  the  queue  is  on 
when  cleared,  subsequent  commands  are  accumulated  until  the  queue  is  ex¬ 
plicitly  turned  off. 


c 

Clearing  an  empty  queue  has  no  effect  and  is  not  an  error. 


The  execute  parameter  instructs  VDI  Management  to  execute  all  commands 
in  the  queue  as  quickly  as  possible.  syQueue  execute  does  not  clear  the 
queue  or  affect  the  queue’s  on  or  off  state.  A  queue  that  has  been  turned  off 
remains  executable. 


Executing  an  empty  queue  has  no  effect  and  is  not  an  error. 


The  state  parameter  turns  the  queue  on  and  off.  State*l  instructs  VDI  Man¬ 
agement  to  store  at  most  10  commands  for  later  execution.  If  more  than  10 
commands  are  issued  while  the  queue  is  on,  the  extra  commands  return  error 
176  (Queue  full),  and  the  commands  in  the  queue  are  left  intact. 


State=0  instructs  VDI  Management  to  resume  immediate  execution  of  com¬ 
mands  without  storing  them  in  the  queue.  Commands  already  in  the  queue 
remain  unchanged  and  unexecuted. 


Turning  a  queue  on  that  is  already  on,  or  off  that  is  already  off  has  no  effect 
and  is  not  an  error. 


The  execute  parameter  always  takes  precedence.  To  execute  commands  and 
clear  the  queue  use  syQueue  clear  execute  or  syQueue  execute  clear. 
Because  execute  has  the  higher  priority,  syQueue  acts  on  execute  first  in 
both  examples.  Similarly,  syQueue  state*l  execute  and  syQueue  state»0 
execute  work  as  expected,  executing  the  queue  then  turning  it  on  or  off, 
respectively. 
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syQueue 

Unqueueable 

commands 


Queued 
commands 
resulting  In  errors 


Notes 


The  following  commands  cannot  be  queued  either  because  requested  informa¬ 
tion  would  be  lost  after  syQueue  execute  or  because  their  behavior  could 
disrupt  the  queue  or  the  execution  of  subsequent  queued  commands. 


Unqueueable  commands 

syCheckError 

syStop 

vmlnit 

syErrorMsg 

vdGetState 

xyGetlnput 

syGetState 

vdlnit 

xyGetState 

sylnit 

vmGetPalette 

xylnit 

syQueue 

vmGetState 

If  an  application  tries  to  queue  an  unqueueable  command  except  syQueue, 
which  executes  immediately,  the  illegal  command  returns  error  177  (Com¬ 
mand  cannot  be  queued)  immediately.  This  error  and  error  176  (Queue  full) 
are  the  only  errors  that  can  be  returned  while  the  queue  is  on.  syQueue  ig¬ 
nores  the  illegal  command.  It  is  not  queued  and  does  not  affect  the  status  of 
the  queue.  Similarly,  if  the  queue  is  fall,  syQueue  ignores  all  attempts  to 
queue  additional  commands. 


If  a  queued  command  results  in  an  error,  the  error  is  not  detected  until 
syQueue  execute.  When  the  error  is  detected,  syQueue  returns  im¬ 
mediately  without  executing  any  remaining  commands  in  the  queue.  How¬ 
ever,  syQueue  does  not  return  an  error.  Therefore,  it  is  good  practice  to 
issue  syCheckError  immediately  after  syQueue  execute  to  determine  if 
an  error  occurred  during  queue  execution.  This  is  the  only  systematic  way  to 
detect  such  errors. 


1.  syQueue  always  executes  immediately  and  cannot  be  queued. 

2.  If  vmSetPalette  is  queued,  the  pointer  information  in  the  command’s  pa¬ 
rameter  block  is  stored  with  the  queue  (see  Section  7).  However,  the  infor¬ 
mation  in  the  palette  array  is  not  stored,  but  is  read  when  the  queue  is 
executed.  Therefore,  if  an  application  changes  the  contents  of  the  palette 
array  between  issuing  and  executing  the  queued  command,  the  modified 
array  will  be  used.  An  application  should  not  deallocate  the  memory  for 
the  palette  array  before  clearing  the  queue.  Doing  so  could  lead  invalid  pal¬ 
ette  information. 
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Returns 

ASCII 


Binary 


See  also: 


Examples 

ASCII 

Turn  on  queue 
and  store 
commands 


Turn  off  queue 
and  execute  new 
commands 
Immediately 


syQueue 

3.  Trying  to  queue  more  than  10  commands  causes  error  176  (Queue  full). 
This  error  can  be  returned  for  any  queueable  command.  Trying  to  queue 
any  unqueueable  command  except  syQueue,  which  executes  immediately, 
causes  error  177  (Command  cannot  be  queued).  Error  177  takes  prece¬ 
dence  over  error  176. 

4.  An  unknown  command  can  be  queued  and  will  not  return  error  2  (Un¬ 
known  command)  until  the  queue  is  executed. 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


vmSetPalette. 


syQueue  state=l 
(returns)  "OK” 

(command  1) 

(returns)  “OK” 

(command  2) 

(returns)  “OK” 

(command  3) 

(returns)  “OK” 

(command  4)  ;  commands  1-4  are  stored  and  not  executed 

(returns)  “OK” 

syQueue  state=0  ;  subsequent  commands  are  not  queued 

(returns)  “OK” 

(command  5) 

(returns)  “OK” 

(command  6) 

(returns)  “OK” 

(command  7)  ;  commands  5-7  are  each  executed  immediately 

(returns)  “OK” 
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syQueue 


Execute  queue, 

syQueue  execute 

then  unqueued 

(returns)  “OK” 

commands 

(command  8) 

(returns)  “OK” 

(command  9) 

(returns)  “OK” 

Reexecute  queue 

syQueue  execute, clear 

and  clear 

(returns)  “OK” 

Binary 

Turn  on  syQueue 

AX 

1034 

BX 

1 

ES:DI[0] 

42 

ES.DI  [4] 

1 

After  return 

AX 

0 

Clear  queue  and 

AX 

1034 

stop  accumulat¬ 

BX 

2 

ing  commands 

ES:DI[0] 

8 

ES:DI[4] 

any  value 

ES:DI[8] 

42 

ES:DI[C] 

0 

After  return 

AX 

0 

;  commands  1-4  are  rapidly  executed  from  the  queue 


;  commands  8  and  9  are  each  executed  immediately 
;  commands  1-4  are  rapidly  executed  and  cleared 


;  syQueue  decimal  ID 
;  number  of  parameters 
;  state  decimal  ID 
;  value  for  “on” 

;  Returns  0  if  successful  (nonzero  if  not) 

;  syQueue  decimal  ID 
;  number  of  parameters 
;  clear  decimal  ID 
;  no  associated  value 
;  state  decimal  ID 
;  value  for  “of!" 

;  returns  0  if  successful  (nonzero  if  not) 
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syStop 


Last  revision:  R  1 .0 
Type:  Core 


Parameters 

ASCII  No  parameters. 

Binary 

Command  code:  1044  decimal. 

No  parameters. 


Description 


Summary 

syStop  frees  all  possible  resources  used  by  the  interfaces  and  VDI  Manage¬ 
ment  to  make  the  resources  available  for  non-IV  use. 

General 

discussion 

syStop  reduces  the  interfaces  and  VDI  Management  to  their  minimum  possi¬ 
ble  configurations  without  actually  unloading  the  VDI  software.  The  com¬ 
mand  frees  resources  such  as  file  handles  and  interrupts  for  use  by  non-IV 
applications.  The  command’s  actions  are  highly  implementation  and  configu¬ 
ration  dependent.  syStop  does  not  change  the  graphics  mode,  therefore, 
applications  must  handle  the  mode  after  exit  separately.  However,  if  VDI 
Management  turned  mode  trapping  on,  which  it  typically  would,  syStop 
turns  it  off. 

After  an  syStop,  all  VDI  commands  are  undefined  except  sylnit.  Upon  re¬ 
sumption  of  IV  activities,  an  sylnit  mutt  be  issued  before  any  other  IV 
command. 

Notes 

1.  An  attempt  to  queue  syStop  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt 

Returns 

ASCII 

On  success:  “OK”. 

On  failure:  “ERROR  n...". 

Binary 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 

See  also: 

sylnit,  syQueue. 
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syStop 


Examples 

ASCII 

Place  VDI  syStop 

Management  In  (returns)  "OK" 
inactive  state 


Binary 


Place  VDI 

AX 

1044 

Management  in 
inactive  state 

BX 

0 

After  return 

AX 

0 

syStop  decimal  ID 
no  parameters 

returns  0  if  successful  (nonzero  if  not) 
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This  section  describes  commands  that  relate  to  the  visual  management  of  the 
display  screen.  The  commands  in  this  section  control  the  graphics  display, 
video  display,  visual  signal  routing,  video  modes,  and  graphics  modes. 

Table  7-1  lists  the  commands  covered  in  this  section,  their  token  numbers, 
and  their  types. 


Table  7-1. 
Visual-management 
command  names, 
token  numbers,  and 
types 


’Upper  or  lower  case  for  command  names  is  not  significant. 
Compliant  implementations  must  support  “Core”  commands. 


ASCII  command 
name1 

Binary  interface 
token  number 
(decimal) 

Type2 

vmFade 

2051 

Core 

vmGetPalette 

2053 

Core 

vmGetState 

2054 

Core 

vmlnit 

2055 

Core 

vmSetGraphics 

2062 

Core 

vmSetPalette 

2063 

Core 

vmSetTrans 

2064 

Core 

vmSetVideo 

2065 

Core 

7.1  Terms  of  reference 


Figure  7—1  shows  a  basic  conceptual  definition  of  a  video  overlay  subsystem. 
It  is  intended  to  convey  the  overlay  card’s  functionality,  but  not  the  hard¬ 
ware  implementation.  The  functionality  applies  to  overlay  boards  that  are 
either  based  primarily  on  graphics  synchronized  to  a  video  signal  or  have  the 
video  corrected  to  match  the  graphics. 
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Figure  7-1. 
A  simplified 
functional  model  of  a 
video  overlay 
subsystem 


Plane  0 


L 


Notes: 

1.  The  definition  includes  two  sources,  plane  0  (video)  from  an  external 
source  such  as  a  videodisc  player  and  plane  1  (graphics)  from  the 
computer.  Each  source  has  an  associated  level  control  or  fader 

2.  The  palette  does  logical-to-physical  color  conversion  and  controls  transpar¬ 
ency.  It  can  be  described  in  terms  of  logical  colors  (number  of  colors  that 
can  be  simultaneously  displayed)  and  physical  colors  (palette  size). 

3.  The  keyer  is  responsible  for  selecting  either  plane  0  or  plane  1  at  a  pixel 
rate  for  output  to  the  display. 

4.  The  dissolve  unit: 

a.  In  its  simplest  form  is  a  switch  between  video  only  and  graphics  over 
video  (a  graphics  ON  I  OFF  capability). 

b.  At  the  next  level  of  complexity  supports  plane  (k->plane  1  cross-fades. 

c.  In  future  systems  may  become  a  pixel-rate  translucency  setting  con¬ 
trolled  by  a  palette  extension  (not  shown). 

7.2  General  information  and  assumptions 


The  general  information  and  assumptions  given  in  this  subsection  were  used 
in  the  definition  of  the  visual-management  commands.  The  material  below  is 
based  on  Intel  80x86  processor  architecture,  MS-DOS  compatible  operating 
systems,  and  standard  IBM-compatible  graphics  modes. 

7.2.1  Overlayable  graphics  modes _ 

Appendix  B  lists  IBM-compatible  graphics  modes  as  they  would  be  returned 
by  BIOS  interrupt  10H,  service  OFH,  including  whether  the  modes  are  text  or 
graphics,  resolutions,  the  adapters  that  support  them,  and  whether  they  are 
overlayable. 


7-2 


Release  R  1.0 


April  15, 1990 


Section  7.  Visual-management  commands  (vm) 


Compliance  requires  that  graphics  modes  zero  through  three  are  guaranteed  to 
be  overlayable  when  the  selected  video  mode  is  NTSC  or  PAL. 


This  means  that  when  the  video  mode  is  not  set  to  “native,”  these  modes  are 
restricted  to  200  lines  regardless  of  the  actual  number  of  lines  that  would  nor¬ 
mally  be  displayed  by  a  given  monitor  adapter.  (See  the  vmSetGraphics 
and  vmSetVideo  commands.) 

7.2.2  Mode  trapping _ _ 

The  visual-management  commands  do  not  control  trapping  interrupt  10H. 

VDI  implementers  may,  and  probably  should,  implement  mode  trapping  to 
protect  against  disruption  of  the  graphics  and  background  video  by  applica¬ 
tions  that  change  modes  using  direct  interrupt  10H  calls  instead  of  using  the 
VDI  visual-management  commands.  This  is  especially  important  for  applica¬ 
tions  that  may  use  separate  graphics  function  libraries  and  similar  tools. 


7.2.3  Genlock  control 


The  ability  to  turn  genlock  on  and  off  is  not  included  in  the  command  set.  The 
recommended  practices  assume  that  all  video  inputs  and  graphics  are  syn¬ 
chronous  at  all  times  from  the  application’s  viewpoint.  Controlling  genlocking 
is  a  video  device  driver  issue  that  is  left  to  the  VDI  implemented 

7.2.4  Graphics  registration  to  the  background  video 

Appendix  A  gives  detailed  information  on  assumed  positions  of  graphics  rela¬ 
tive  to  background  video.  The  information  in  the  appendix  should  furnish  reli¬ 
able  registration  within  about  two  pixels  both  horizontally  and  vertically. 

However,  applications  that  have  critical  registration  requirements  should  in¬ 
clude  a  position  reference  frame  to  allow  dynamic  positioning  of  the  graphics 
plane  at  run-time.  The  command  set  provides  commands  for  varying  the 
graphics  origin  both  horizontally  and  vertically.  An  extended  feature  sup¬ 
ports  setting  the  total  width  of  the  active  graphics. 

7.2.5  VGA  graphics  versus  CGA  and  EGA  graphics 

Some  graphics  modes,  in  particular  620  x  200  and  320  x  200  resolution 
modes,  are  displayed  differently  by  VGA  adapters  versus  CGA  and  EGA 
adapters.  VGA  adapters  display  these  modes  so  that  the  width  of  the  active 
graphics  area  is  equal  to  the  width  of  the  background  video.  CGA  and  EGA 
adapters  leave  right  and  left  borders  in  these  modes.  Therefore,  for  CGA  and 
EGA  applications  to  be  portable  to  VGA-based  systems,  the  VGA  system 
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must  have  the  ability  to  display  these  modes  at  full  width  and  as  they  would 
be  displayed  by  a  CGA  or  EGA  adapter.  Appendix  A  gives  detailed  informa¬ 
tion  on  VGA  emulation  of  CGA  and  EGA  graphics  displays. 


Compliance  requires  VGA  emulation  of  CGA  and  EGA  graphics  displays. 


7.2.6  Logical  versus  physical  colors _ 

The  visual-management  commands  distinguish  between  logical  and  physical 
colors.  A  typical  computer  cannot  display  all  available  colors  simultaneously. 
For  example,  in  VGA  mode  19,  the  system  can  simultaneously  display  256  col¬ 
ors  taken  from  262,144  possible  colors.  The  visual  management  commands 
refer  to  the  number  of  colors  that  can  be  displayed  simultaneously,  here  256, 
as  the  number  of  available  logical  colors.  The  commands  refer  to  the  total  pos¬ 
sible  colors,  here  262,144,  as  the  number  of  available  physical  colors — this  is 
also  commonly  called  the  palette  size. 

7.3  Rounding  methods  for  fades  and  dissolves 


The  visual  management  vmFade  command  must  be  supported.  However, 
compliant  VDI  Management  software  can  be  developed  for  TV  hardware  with¬ 
out  fade  circuitry.  For  systems  with  fade  circuitry,  variations  in  available 
fade  levels  must  be  treated  consistently. 

Applications  pass  fade  levels  to  VDI  Management  as  integers  in  the  range  0- 
255,  which  represent  full  off  and  full  on,  respectively.  Intermediate  values 
represent  a  linear  transition  of  intensity  from  full  off  to  full  on.  Dissolve 
levels  are  also  passed  as  integers,  where  0  represents  display  of  video  only 
and  255  represents  hard  keying  (transparent  colors  are  full  video,  opaque  col¬ 
ors  are  full  graphics). 

VDI  Management  allocates  each  available  hardware  setting  a  level  in  the 
range  0-255  and  rounds  passed  values  to  the  nearest  possible  level.  For  ex¬ 
ample,  if  the  hardware  furnishes  four  fade  levels  with  intensities  of  full  off, 

VS  on.  Vs  on,  and  full  on,  these  are  allocated  the  numeric  values  0,  85, 170, 
and  255,  respectively.  Passed  values  in  the  range  0-42  are  rounded  to  full  off, 
43-127  to  V3  intensity,  128-212  to  %  intensity,  and  213-255  to  full  on. 

If  a  fader  is  uneven,  rounding  ranges  are  adjusted  accordingly.  For  example, 
if  a  fader  can  do  full  off,  Vi  on,  Vi  on,  and  full  on  only,  these  are  allocated  the 
values  0, 128, 192,  and  255. 

For  fades  that  use  nonzero  time  periods,  the  fade  levels  are  calculated  as: 

current  level  =  start  level  +  f^rjf  s^e  S.tart  x  {end  level  -  start  level) 

I  fade  duration 
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The  fade  levels  are  then  rounded  in  the  usual  way.  Assume  a  fade  from  full 
off  to  full  on  over  2.55  seconds  on  a  system  that  can  fade  to  off,  Vi  on,  Vi  on, 
and  full  on.  The  fader  stays  off  for  the  first  0.425  seconds,  at  Vi  from  0.425  to 
1.275  seconds,  at  %  from  1.275  to  2.125  seconds,  and  at  full  on  from  2.125  to 
2.55  seconds.  Note  that  noninteger  fade  levels  round  in  the  usual  way. 

Applications  can  assume  that  levels  0  and  255  are  available.  On  a  system 
with  no  fade  or  dissolve  circuitry,  VDI  Management  switches  to  full  off  for 
levels  0-127  and  full  on  for  128-255. 

Note:  Application  authors  should  not  assume  rounded  times  are  exact.  On 
typical  systems,  the  resolution  of  the  tick  interrupt  or  system  clock  will  re¬ 
strict  the  accuracy  of  timings. 
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vmFade 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return  1  Type 
value  as 

^11 

Default  if 
parameter 
not  used 

dlevel 

Core 

Dissolve  level, 

0-255 

Integer 

None 

N/A 

No  action 

glevel 

Core 

Graphics  level, 
0-255 

Integer 

None 

N/A 

No  action 

vlevel 

Core 

Video  level,  0-255 

Integer 

None 

N/A 

No  action 

time 

Core 

Seconds  for  fade 
or  dissolve 

Real 

None 

N/A 

0 

wait 

Core 

None 

N/A 

None 

N/A 

No  wait 

Exactly  one  of  dlevel,  glevel,  or  vlevel  must  be  specified  or  an  error  is  returned. 


Binary 

Command  code:  2051  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

dlevel 

Core 

17 

Integer 

Dissolve  level, 
0-255 

Actual  level  after 
rounding  if  required 

No  action 

glevel 

Core 

26 

Integer 

Graphics  level, 
0-255 

Actual  level  after 
rounding  if  required 

No  action 

vlevel 

Core 

52 

Integer 

Video  level,  0-255 

Actual  level  after 
rounding  if  required 

No  action 

time 

Core 

47 

Real’ 

Seconds  for  fade 
or  dissolve 

None 

0 

wait 

Core 

54 

N/A 

None 

None 

No  wait 

|  Exactly  one  of  dlevel,  glevel,  or  vlevel  must  be  specified  or  an  error  is  returned. 


’See  Section  4.4.2  for  the  hexadecimal  representation  of  this  value. 
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Description 

Summary 

General 

discussion 

Dlevel  parameter 


vmFade 


vmFade  sets  th*  absolute  levels  of  the  graphics  plane  (glevel)  and  the  video 
plane  (vlevel),  and  the  relative  levels  of  video  to  graphics  (dlevel)  displayed 
on  the  screen.  The  specified  level  parameter  changes  to  the  specified  level 
value  over  the  specified  time.  The  command  returns  immediately  or  after  the 
specified  level  is  reached  if  wait  is  specified.  (Figure  7-1  in  Section  7.1  shows 
the  relationship  of  the  level  parameters  to  a  video  overlay  subsystem.) 


Actual  levels  may  vary  from  requested  levels  depending  on  system  capabili¬ 
ties.  If  a  system  supports  less  than  256  levels  for  a  given  level  parameter, 

VDI  Management  rounds  the  requested  level  to  the  closest  supported  level. 
vmGetState  returns  the  actual  level  that  was  set  after  any  required  round¬ 
ing  when  vmFade  has  finished  execution.  Similarly,  the  binary  version  of 
vmFade  returns  the  actual  level  that  will  be  set  after  any  rounding  in  the  pa¬ 
rameter  packet.  (See  Section  7.3  for  more  information  on  rounding  levels.) 


The  dlevel  parameter  creates  transitions  or  dissolves  between  video  only  and 
hard  keying  (transparent  colors  are  full  video,  opaque  colors  are  full  graph¬ 
ics).  The  parameter  can  be  used  to  go  from  all  video  to  all  graphics  or,  when 
set  to  middle  values,  to  create  “ghosting”  or  highlighted  effects  with  video 
showing  through  graphics.  If  a  system  cannot  do  dissolves,  it  switches  to  all 
video  when  dlevel  is  0-127  and  to  hard  keying  when  dlevel  is  128-255. 


With  dlevelsO  the  video  plane  only  is  visible.  With  dlevel=255  nontrans¬ 
parent  colors  display  graphics  at  full  intensity  and  transparent  colors  display 
video  only,  assuming  vmSetTrans  state*l  has  been  issued.  Assuming 
dlevel«255,  to  create  a  transition  from  graphics  only  to  video  only,  turn 
transparency  off  with  vmSetTrans  state«0,  then  issue  vmFade  dlevel=0. 


Dlevel  differs  from  glevel  and  vlevel  (see  below)  in  that  it  controls  the  rela¬ 
tive  mix  of  video  and  graphics.  Unlike  glevel  and  vlevel,  dlevel  lets  graph¬ 
ics  appear  mixed  with  video  so  that  video  and  graphics  are  both  visible  in  a 
ratio  determined  by  the  dlevel  parameter.  In  contrast,  glevel  and  vlevel  set 
the  total  amount  of  video  or  graphics  signal  used. 


Because  dlevel  sets  the  ratio  of  video  to  graphics,  it  is  affected  by  glevel  and 
vlevel  values.  For  example  if  vlevel*0,  vmFade  dlevel=255  will  display 
graphics  at  full  intensity  but  will  not  display  video  because  the  video  signal 
has  been  turned  off. 
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vmFade 

Glevei  parameter 

Vlevei  parameter 

Time  parameter 

Wait  parameter 


Notes 


The  glevei  parameter  sets  the  absolute  intensity  of  the  graphics  plane  in  the 
range  0  to  255  (full  off  to  full  on).  If  a  system  supports  graphics  on  and  off 
only,  it  switches  graphics  on  if  glevei  is  128-255  and  off  if  glevei  is  0-127. 


The  vlevei  parameter  sets  the  absolute  intensity  of  the  video  plane  in  the 
range  0  to  255  (full  off  to  full  on).  If  a  system  supports  video  on  and  off  only,  it 
switches  video  on  if  vlevei  is  128-255  and  off  if  vlevei  is  0-127. 


The  time  parameter  specifies  the  number  of  seconds  over  which  the  fade  or 
dissolve  occurs.  If  necessary,  VDI  Management  rounds  time  to  the  nearest 
value  the  system  supports. 


The  time  parameter  functions  the  same  ev^.  he  hardware  or  system  soft¬ 
ware  does  not  support  fades  or  dissolves. 


If  the  wait  parameter  is  specified,  vmFade  does  not  return  until  the  fade  or 
dissolve  has  reached  the  specified  level  value  at  the  end  of  the  specified  time. 
If  wait  is  not  used,  vmFade  returns  immediately  and  the  fade  or  dissolve  ex¬ 
ecutes  as  a  background  task. 


The  wait  parameter  functions  the  same  even  if  the  system  does  not  support 
fades  or  dissolves. 


1.  vmGetState  issued  with  the  appropriate  level  parameter  returns  the  cur¬ 
rent  dissolve  or  fade  level.  This  command  can  be  used  to  determine  if  a 
background  fade  is  complete.  However,  when  a  fade  or  dissolve  is  com¬ 
plete,  the  value  returned  by  vmGetState  may  not  agree  with  the  re¬ 
quested  level  because  of  rounding.  Therefore,  programmers  should  test  for 
limits  instead  of  exact  values. 

2.  If  a  system  cannot  do  fades  or  dissolves,  it  switches  to  level  255  when  a 
levjl  parameter  is  set  to  128-255,  and  to  level  0  when  a  level  is  set  to  0- 
1L  .  However,  this  does  not  affect  the  wait  and  time  parameters.  For  ex¬ 
ample,  if  the  system  is  incapable  of  dissolves,  after  the  commands: 

vmFade  dlevel=0 

vmFade  d)evel=255,  tim<'^=60,  wait 

the  system  will  remain  at  level  0  for  30  seconds,  then  switch  to  level  255, 
then  return  after  another  30  seconds.  (See  Section  7.3  for  more  informa¬ 
tion  on  rounding  times.) 
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Returns 

ASCII 


Binary 


See  also: 


Examples 

ASCII 

Dissolve  to  all 
video  over  1.5 
seconds,  do  not 
return  until 
complete 

Set  display  to 
hard  keying 
Immediately 

Set  video  and 
graphics  to  50% 
relative  intensity 

Fade  graphics  to 
full  intensity  over 
0.3  seconds 

Fade  video  to  zero 
over  1  second,  do 
not  return  until 
complete 

Set  video  to  zero 
immediately 


vmFade 


3.  Only  one  level  may  be  set  with  a  single  call  to  vmFade.  However,  vmFade 
commands  can  be  queued  with  syQueue  to  create  the  effect  of  multiple,  si¬ 
multaneous  fades  and  dissolves. 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0.  Value  associated  with  dlevel,  glevel,  or  vlevel  parame¬ 
ter  is  a  32-bit  integer  that  gives  the  actual  level  that  will  be  set  after  round¬ 
ing  if  required. 

On  failure:  AX  =  error  number. 


syQueue,  vmGetState,  vmSetTrans. 


vmFade  dlevel=0,time=  1.5, wait 
(returns)  “0” 


vmFade  dlevel=255 
(returns)  “OK" 


vmFade  dlevel=128 
(returns)  “OK” 


vmFade  glevel=255,time=.3 
(returns)  “255” 


vmFade  vlevel=0,time=l,wait 
(returns)  “0” 


vmFade  vlevel =0 
(returns)  “OK” 
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vmFade 


Set  video  to  half 

vmFade  vlevel=128 

Intensity 

Immediately 

(returns)  “OK” 

Binary 

Dissolve  to  0  over 

AX 

2051 

;  vmFade  decimal  ID 

2.5  seconds  and 

BX 

3 

;  number  of  parameters 

return  when  done 

ES:DI[0] 

17 

;  dlevel  decimal  ID 

ES:DI[4] 

0 

;  dlevel  value 

ES:DI[8] 

47 

;  time  decimal  ID 

ES:DI[C] 

2.5 

;  time  value  in  seconds.  See  Section  4.4.2  for  the 
;  hexadecimal  representation  of  this  value. 

ES:DI[10] 

54 

;  wait  decimal  ID 

ES:DI[14] 

any  value 

;  no  associated  value 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

ES:DI[4] 

0 

;  actual  level  that  will  be  set  after  rounding  if  required 
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vmGetPalette 


Last  revision:  R  1.0 


Type:  core 


Parameters 


ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

color 

Core 

Logical  color 
number 

Integer 

None 

N/A 

Causes 

error 

r 

Core 

None 

N/A 

Red  value,  0-255 

Integer 

No  action 

g 

Core 

None 

N/A 

Green  value,  0-255 

Integer 

No  action 

b 

Core 

None 

N/A 

Blue  value,  0-255 

Integer 

No  action 

j  Exactly  one  color  and  at  least  one  of  r,  g,  and  b  are  required  or  an  error  is  returned. 

Binary 

Command  code:  2053  decimal 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

color 

Core 

Integer 

Logical  color 
number 

None 

Causes 

error 

r 

Core 

38 

Integer 

Any  value 

Red  value,  0-255 

No  action 

g 

Core 

25 

Integer 

Any  value 

Green  value,  0-255 

No  action 

b 

Core 

4 

Integer 

Any  value 

Blue  value,  0-255 

No  action 

length 

Core 

31 

Integer 

Number  of  color 
array  entries1 

Number  of  color 
array  entries1 

No  action 

array 

Core 

1 

Pointer 

Pointer  to  color 
array 

Pointer  to  color 
array 

No  action 

Either  exactly  one  color  and  at  least  one  of  r,  g,  and  b  are  required:  or  color,  length, 
and  array  must  be  used  together;  or  an  error  is  returned. 

1cotor  array  entry  *=  4  bytes  comprised  of  3  components  +  reserved  byte. 
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vmGetPalette 

Description 

Summary 


General 

discussion 


Color  +  r,  g,  and 
b  parameters 


Color  +  length 
and  array 
parameters 
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vmGetPalette  returns  the  amounts  of  red,  green,  and  blue  components  in  a 
specified  logical  color  via  the  ASCII  interface  or  one  or  more  sets  of  compo¬ 
nent  values  for  contiguous  logical  colors  via  the  binary  interface. 

vmGetpalette  returns  the  proportions  of  the  red,  green,  and  blue  compo¬ 
nents  in  a  logical  color  as  real  numbers  in  the  range  0-255  where  255  is  fully 
saturated  for  each  component.  Component  values  are  returned  for  single  col¬ 
ors  via  the  ASCII  interface  and  for  single  or  multiple  colors  via  the  binary 
interface  depending  on  the  calling  parameters. 

vmGetState  logcolors  returns  the  number  of  available  logical  colors  (colors 
that  can  be  simultaneously  displayed).  vmGetState  physcolors  returns  the 
number  of  available  physical  colors  (palette  size).  vmSetPalette  assigns 
physical  colors  to  logical  colors,  and  vmGetPalette  returns  the  component 
values  for  the  assigned  colors.  For  example,  a  system  might  support  16  logi¬ 
cal  colors  from  a  palette  of 4096  physical  colors.  Logical  color  3  might  be 
bright  cyan  with  component  values  of  r=0,  b=255,  g=255. 

These  parameters  apply  to  both  the  ASCII  and  binary  interfaces.  The  color 
parameter  defines  the  logical  color  number  for  which  r,  g,  and  b  component 
values  are  returned.  Logical  color  numbers  range  from  zero  to  the  value  re¬ 
turned  by  vmGetState  logcolors  minus  one. 

Exactly  one  color  parameter  must  be  listed.  Specifying  color  twice  causes  er¬ 
ror  54  (Parameter  used  more  than  once),  and  omitting  color  or  failing  to  in¬ 
clude  at  least  one  of  r,  g,  and  b  causes  error  49  (Insufficient  parameters). 

Any  or  all  of  r,  g,  and  b  can  be  fisted  with  a  color.  vmGetPalette  returns  a 
comma-separated  fist  of  the  requested  integer  values  via  the  ASCII  interface 
or  a  32-bit  integer  for  each  requested  component  via  the  binary  interface. 

The  length  and  array  parameters  are  available  with  the  binary  interface 
only.  They  furnish  a  way  to  pass  a  pointer  to  an  array  for  storing  a  set  of  pal¬ 
ette  values  in  application  memory.  The  value  associated  with  array  is  a  32- 
bit  pointer  to  a  memory  block  containing  one  or  more  4-byte  structures. 

Array  must  point  to  memory  allocated  by  the  application  The  contents  of 
each  structure  in  the  palette  array  are: 

•  Byte  0,  the  least  significant  byte,  represents  blue. 

•  Byte  1  represents  green. 

•  Byte  2  represents  red. 

•  Byte  3  is  reserved  and  always  set  to  zero. 
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Parameters 
resulting  in  errors 

i 

Notes 


i 


l 

Returns 

*  ASCII 

►  Binary 


► 


►  See  also: 


Section  7.  Visual-management  commands  (vm) 


vmGetPalette 


The  length  parameter  specifies  the  number  of  4-byte  structures  in  the  array. 
The  values  in  the  first  structure  of  the  array  are  for  the  logical  color  number 
specified  by  the  color  parameter.  The  second  structure  relates  to  color+1, 
the  third  to  color+2,  an  so  on  up  to  the  number  of  structures  specified  by 
length.  (See  Section  4.4.2  for  more  information  about  palette  arrays.) 

If  a  parameter  causes  an  error,  vmGetPalette  returns  immediately  with  an 
error  message.  The  command  does  not  return  partial  responses  for  other  pa¬ 
rameters  that  do  not  cause  errors. 


1.  Values  returned  by  vmGetPalette  may  not  exactly  match  values  set  with 
vmSetPalette  because  of  rounding  when  vmSetPalette  component  val¬ 
ues  do  not  match  the  component  levels  available  on  a  specific  system.  For 
example,  a  system  with  four  levels  per  component  (0,  85, 170,  and  255) 
will  return  a  component  value  of  85  even  though  the  value  specified  by 
vmSetPalette  was  50. 

2.  VDI  Management  does  not  maintain  palette  arrays  that  are  directly  acces¬ 
sible  by  applications.  Palette  arrays  for  vmGetPalette  must  be  allocated 
by  the  application.  To  allocate  memory  in  bytes  for  a  palette  array,  use 
length  x  4. 

3.  Trying  to  queue  vmGetPalette  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 


On  success:  Comma-separated  list  of  requested  r,  g,  and  b  component  val¬ 
ues  in  the  range  “0”  to  “255”  for  color. 

On  Failure:  “ERROR  n.. 

On  success:  AX  =  0.  Values  associated  with  r,  g,  and  b  parameters  are  32- 
bit  integers  in  the  range  0-255  for  color.  Value  associated  with  length  pa¬ 
rameter  is  a  32-bit  integer  giving  the  number  of  4-byte  structures  in  a  palette 
array  allocated  by  the  application.  Value  associated  with  array  parameter  is 
a  32-bit  pointer  to  the  palette  array.  With  length  and  array,  the  value  asso¬ 
ciated  with  color  is  the  first  logical  color  in  a  contiguous  series  in  the  palette 
array. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:D1  are  undefined  and  should  be  ignored. 


syQueue,  vmGetState,  vmSetPalette. 


) 
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Examples 


ASCII 

Return  values  for  vmGetPalette  color=0,r,g,b 

all  parameters  for  (retums)  “255,127,0”  ;  logical  color  0  has  red=255,  green=127,  blue=0 

logical  color  0 


Return  red  vmGetPalette  color=l,r 

component  for  (returns)  “170”  ;  logical  color  1  has  a  red  component  of  170 

logical  color  1 


Binary 


Get  green 

AX 

2053 

;  vmGetPalette  decimal  ID 

component  value 

BX 

2 

:  number  of  parameters 

for  color  number  3 

ES:DI[0J 

9 

;  color  decimal  ID 

ES:DI[4] 

3 

;  color  number 

ES:DI[8] 

25 

;  g  decimal  ID 

ES:DI[C] 

any  value 

;  place  holder  for  value  on  return 

After  return 

AX 

0 

;  retums  0  if  successful  (nonzero  if  not) 

ES:DI[C] 

g  value 

;  green  value  for  color  3 

Get  color  values 

AX 

2053 

;  vmGetPalette  decimal  ID 

from  color  3  to  9 

BX 

3 

:  number  of  parameters 

(binary  interface 

only) 

ES:DI[0] 

9 

;  color  decimal  ID 

ES:DI[4] 

3 

;  first  color  to  list  in  palette  array 

ES:DI[8] 

31 

;  length  decimal  ID 

ES:DI[C] 

7 

;  number  of  color  structures  in  palette  array 

ES:DI[10] 

1 

;  array  decimal  ID 

ES:DI[14]  pointer 

;  pointer  to  palette  array  in  application  memory 

After  return 

AX 

0 

;  retums  0  if  successful  (nonzero  if  not) 

ES:DI[14]  pointer 

;  pointer  to  same  array  with  updated  component  values 

0 
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vmGetState 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated 
calling  value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

color 

Core 

Logical  color 
number 

Integer 

1  (transparent)  | 

0  (opaque) 

Integer 

No  action 

defsource 

Core 

None 

N/A 

Default  video 
source,  0-15 

Integer 

No  action 

dlevel 

Core 

None 

N/A 

Current  level, 

0-255 

Integer 

No  action 

emulation 

Core 

None 

N/A 

1  (on)  |  0  (off) 

Integer 

No  action 

enable 

Core 

None 

N/A 

1  (on)  |  0  (off) 

Integer 

No  action 

horzpix 

Core 

None 

N/A 

Total  horizontal 
pixels  in  current 
gmode 

Integer 

No  action 

glevel 

Core 

None 

N/A 

Current  level, 

0-255 

Integer 

No  action 

gmode 

Core 

None 

N/A 

Current  graphics 
mode 

Integer 

No  action 

logcolors 

Core 

None 

N/A 

Total  available 

Integer 

No  action 

physcolors 

Core 

None 

N/A 

Total  available 

Integer 

No  action 

transcolors 

Core 

None 

N/A 

Total  available 

Integer 

No  action 

tsources 

Core 

None 

N/A 

Total  video  sour¬ 
ces  installed,  0-15 

Integer 

No  action 

vertpix 

Core 

None 

N/A 

Total  vertical  pixels 
in  current  gmode 

Integer 

No  action 

vlevel 

Core 

None 

N/A 

Current  level, 

0-255 

Integer 

No  action 

vmode 

Core 

None 

N/A 

0  (native)  | 

1  (NTSC)  1 2  (PAL) 

Integer 

No  action 

width 

Extended 

None 

N/A 

Graphics  width  in 

\1S 

Real 

No  action 

xoffset 

Core 

None 

N/A 

Graphics  offset  in 
pixels 

Integer 

No  action 

yoffset 

Core 

None 

N/A 

Graphics  offset  in 
pixels 

Integer 

No  action 

|  At  least  one  parameter  is  required  or  an  error  is  returned.  | 
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vmGetState 

Binary 

Command  code:  2054  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated 
calling  value 

Associated  return  value 

Default  if 
parameter 
not  used 

color 

Core 

9 

Integer 

Logical 
color  number 

1  (transparent)  | 

0  (opaque) 

No  action 

defsource 

Core 

13 

Integer 

Any  value 

Default  video  source, 
0-15 

No  action 

dlevel 

Core 

17 

Integer 

Any  value 

Current  level,  0-255 

No  action 

emulation 

Core 

19 

Integer 

Any  value 

1  (on)  [  0  (off) 

No  action 

enable 

Core 

20 

Integer 

Any  value 

1  (on)  |  0  (off) 

No  action 

glevel 

Core 

26 

Integer 

Any  value 

Current  level,  0-255 

No  action 

gmode 

Core 

27 

Integer 

Any  value 

Current  graphics 
mode 

No  action 

horzpix 

Core 

28 

Integer 

Any  value 

Total  horizontal  pixels 
in  current  gmode 

No  action 

logcolors 

Core 

32 

Integer 

Any  value 

Total  available 

No  action 

physcolors 

Core 

36 

Integer 

Any  value 

Total  available 

No  action 

transcolors 

Core 

49 

Integer 

Any  value 

Total  available 

No  action 

tsources 

Core 

46 

Integer 

Any  value 

Total  video  sources 
installed,  0-15 

No  action 

vertpix 

Core 

50 

Integer 

Any  value 

Total  vertical  pixels  in 
current  gmode 

No  action 

vlevel 

Core 

52 

Integer 

Any  value 

Current  level,  0-255 

No  action 

vmode 

Core 

53 

Integer 

Any  value 

0  (native)  1 1  (NTSC) 

1 2  (PAL) 

No  action 

width 

Extended 

55 

Real 

Any  value 

Graphics  width  in  ps1 

No  action 

xoffset 

Core 

60 

Integer 

Any  value 

Graphics  offset  in 
pixels 

No  action 

yoffset 

Core 

66 

Integer 

Any  value 

Graphics  offset  in 
pixels 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


^ee  Section  4.4.2  for  the  hexadecimal  representation  of  this  value. 
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Description 

Summary 


Color  parameter 


Enable  parameter 


Defsource 

parameter 


Dlevel,  glevel, 
and  vievel 
parameters 


Emulation 

parameter 


vmGetState 


vm  Get  state  returns  information  about  the  state  of  the  visual-management 
service  group  including  the  current  settings  of  variable  parameters  and  avail¬ 
able  resources  such  as  palette  size  and  number  of  video  sources. 


The  color  parameter  requests  the  transparency  setting  for  a  specified  logical 
color  number.  A  return  value  of  one  means  that  the  specified  color  is  set  to 
transparent;  zero  means  the  specified  color  is  opaque.  (See  enable  below). 


The  enable  parameter  returns  one  if  logically  transparent  colors  are  cur¬ 
rently  physically  transparent  to  the  video  plane.  Transparent  colors  are  those 
which  have  been  set  to  transparent  with  vmSetTrans  color=(logical  color 
number), state=on.  After  vmSetTrans  enable=l,  these  colors  reveal  the 
video  plane.  After  vmSetTrans  enable=0,  all  graphics  colors  including 
transparent  colors  are  visible  and  entirely  cover  the  video  plane. 


The  defsource  parameter  returns  the  default  logical  video  source  in  the 
range  0-15.  Note  that  a  video  source  is  always  selected,  but  the  source  num¬ 
ber  does  not  necessarily  equal  the  default  device  number.  For  example,  logi¬ 
cal  player  zero  may  be  logical  video  source  one.  This  mapping  is  determined 
at  VDI  installation/configuration  time.  The  default  video  source  is  defined  as 
source  zero  unless  vmSetVideo  defsource  is  used  to  change  it. 


The  dlevel,  glevel,  and  vievel  parameters  return  current  levels  in  the 
range  0-255  for  the  dissolve  level,  graphics  plane,  and  the  video  plane,  respec¬ 
tively.  The  return  values  are  actual  values  and  may  differ  from  the  values  re¬ 
quested  by  vmFade  because  of  rounding. 


Note:  The  values  returned  by  these  parameters  are  the  levels  at  the  time  of 
the  request,  which  may  not  equal  the  requested  or  actual  target  levels  for  dis¬ 
solves  and  fades  that  may  be  in  progress. 


The  emulation  parameter  returns  the  state  of  VGA  emulation  of  CGA  and 
EGA  graphics  versus  VGA  native  mode.  In  some  graphics  modes,  CGA  and 
EGA  graphics  displayed  with  a  CGA  or  EGA  adapter  have  different  horizon¬ 
tal  registration  relative  to  video  compared  to  graphics  with  the  same  mode 
number  displayed  widi  a  VGA  adapter.  Implementations  that  support  CGA 
or  EGA  graphics  only  always  return  one  (on).  (See  Appendix  A  for  more  infor¬ 
mation  on  VGA  emulation  of  CGA  and  EGA  graphics.) 
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vmGetState 


Gmode  parameter 


Horzpix  and 

vertpix 

parameters 


Logcolors  and 

physcolors 

parameters 


Transcolors 

parameter 


Tsources 

parameter 


Vmode  parameter 


Width  parameter 


7-18 


The  gmode  parameter  returns  the  current  video  mode  exactly  as  it  would  be 
returned  by  a  request  to  BIOS  interrupt  10H,  service  OFH  (see  Appendix  B). 


The  horzpix  and  vertpix  parameters  return  the  current  pixel  resolution. 
These  parameters  are  especially  useful  for  determining  the  resolution  of  text 
modes  where  the  number  of  pixels  displayed  on  the  screen  varies  from  one 
graphics  device  to  another  (CGA,  EGA,  MCGA,  VGA). 


The  logcolors  parameter  returns  the  number  of  logical  colors  (simulta¬ 
neously  displayable  colors)  that  are  available.  The  physcolors  parameter  re¬ 
turns  the  range  of  colors  (palette  size)  that  can  be  assigned  to  logical  colors. 
Both  return  values  are  determined  by  the  capabilities  of  the  graphics  hard¬ 
ware  and  mode. 


The  transcolors  parameter  returns  the  total  number  of  logical  colors  that 
can  be  made  transparent  with  vmSetTrans. 


The  tsources  parameter  returns  the  total  number  of  video  sources  for  which 
VDI  Management  was  installed. 


The  vmode  parameter  returns  the  video  mode  as  set  by  vmSetVideo.  The 
vmode  is  either  0  (native),  1  (NTSC),  or  2  (PAL).  Native  mode  is  a  nonover¬ 
lay  mode,  but  does  not  change  overlay  parameters.  NTSC  and  PAL  indicate 
the  system  is  configured  for  the  indicated  video  standard. 


The  width  parameter  returns  the  total  graphics  width  in  microseconds.  This 
parameter  lets  applications  accurately  establish  the  right  edge  of  the  active 
graphics  area  relative  to  background  video.  (See  Appendix  A  for  more  infor¬ 
mation  on  graphics  registration.) 


Width  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). 
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» 

vmGetState 

Xoffset  and 

yoffset 

parameters 

The  xoffset  and  yoffset  give  the  offset  of  the  graphics  plane  relative  to  the 
video  plane  in  pixels  as  set  by  vmSetGraphics.  The  origin  of  the  graphics 
plane  is  the  upper  left  corner  of  the  graphics  display  area. 

\ 

Parameters 
resulting  In  errors 

If  a  parameter  causes  an  error,  vmGetState  returns  immediately  with  an  er¬ 
ror  message.  The  command  does  not  return  partial  responses  for  other  param¬ 
eters  that  do  not  cause  errors. 

i 

Notes 

1.  Trying  to  queue  vmGetState  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 

► 

Returns 

ASCII 

On  success:  Comma-separated  list  of  values  for  requested  parameters  as  de¬ 
scribed  above. 

On  failure:  “ERROR  n...”. 

p 

Binary 

On  success:  AX  =  0.  Values  associated  with  requested  parameters  are  32-bit 
values  of  the  types  given  in  the  binary  parameter  table  above. 

► 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 

See  also: 

syGetState,  syQueue,  vdGetState,  vmFade,  vmGetPalette,  vmlnit,  vmSet¬ 
Graphics,  vmSetVideo,  vmSetTrans,  xyGetState. 

► 

Examples 

i 

ASCII 

Get  the  current 
graphics  level  and 
mode 

vmGetState  glevel.gmode 

(returns)  “0,14”  ;  graphics  level  currently  set  to  0 

;  graphics  mode  is  14  (640  X  200) 

► 

Determine 
whether  logical 
color  three  Is 
transparent 

vmGetState  color=3 

(returns)  “1"  ;  color  number  3  is  set  for  transparency 

t 
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vmGetState 

Binary 


Get  current 

AX 

2054 

;  vmGetState  decimal  ID 

graphics  level, 

BX 

3 

;  number  of  parameters 

graphics  mode, 

ES:DI[0] 

26 

;  glevel  decimal  ID 

and  number  of 

ES:DI[4] 

any  value 

;  place  holder  for  value  on  return 

available  physical 

ES:DI[8] 

27 

;  gmode  decimal  ID 

colors 

ES:DI[C] 

any  value 

;  place  holder  for  value  on  return 

ES:DI[10] 

36 

;  physcolors  decimal  ID 

ES:DI[14] 

any  value 

;  place  holder  for  value  on  return 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

ES:DI[4] 

level  value 

;  contains  current  graphics  level 

ES:DI[C] 

gmode  value 

;  contains  current  graphics  mode  number 

ES:DI[14] 

physcolors  value  ;  contains  available  physical  colors 
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vmlnit 

Parameters 

ASCII 

Binary 

Command  code: 

Description 

Summary 

Conditions  set  by 
vmlnit 


Last  revision:  R  1.0 
Type:  core 


No  parameters. 


2055  decimal. 
No  parameters. 


vmlnit  initializes  the  visual  management  hardware  and  software,  placing 
both  in  a  known  state. 

vmlnit  sets  the  parameters  in  the  following  table  to  the  specified  values. 


Parameter  values  set  by  vmlnit 


Parameter 

Value 

Command  reference 

dlevel 

255  (hard  keying) 

vmFade 

emulation 

1  (on) 

vmSetGraphics 

enable 

0  (off) 

vmSetTrans 

glevel 

255  (full  intensity) 

vmFade 

gmode 

Current  value 

vmSetGraphics 

horzpix 

Current  value 

None 

logcolors 

System  limit  for  gmode 

None 

physcolors 

System  limit  for  gmode 

None 

state 

0  (transparency  off) 

vmSetTrans 

transcolors 

System  limit  for  gmode 

None 

width1 

System  default  for  gmode 

vmSetGraphics 

vertpix 

Current  value 

None 

vlevel 

0  (off) 

vmFade 

vmode 

0  (native) 

vmSetVideo 

xoffset 

0 

vmSetGraphics 

yoffset 

0 

vmSetGraphics 

1 1f  supported. 
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vmlnit 


Notes 


1.  In  typical  VDI  Management  implementations,  vmlnit  turns  mode  trapping 
on  to  intercept  video  BIOS  interrupt  10H  calls  so  that  applications  cannot 
make  graphics  mode  changes  without  VDI  Management’s  knowledge.  This 
is  especially  important  for  applications  that  use  graphics  libraries  and  sim¬ 
ilar  tool  kits.  If  vmlnit  turns  mode  trapping  on,  syStop  should  turn  it  off. 

2.  The  default  defsource  is  video  source  zero.  However,  if  an  application  uses 
vmSetVideo  defsource  to  change  the  source,  a  subsequent  vmlnit  does 
not  reset  the  source  to  zero  and  any  applicable  parameters  affect  the 
source  set  by  vmSetVideo. 

3.  Trying  to  queue  vmlnit  causes  error  177  (Command  cannot  be  queued)  at 
the  time  of  the  attempt. 


Returns 

ASCII  On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

Bln^.  y  On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


See  also:  sylnit,  syStop,  vdlnit,  xylnit. 


Examples 

ASCII 


Initialize  visual 

vmlnit 

management 

services 

(returns)  “OK” 

Binary  examples 

Initialize  visual 

AX 

2055 

;  vmlnit  decimal  ID 

management 

services 

BX 

0 

;  number  of  parameters 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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vmSetGraphics 

Emulation  The  emulation  parameter  controls  VGA  emulation  of  CGA  and  EGA  horizon- 

parameter  tal  graphics  positioning  in  common  modes.  If  emulation=l,  the  default  set 

by  vmlnit,  then  a  VGA  adapter  will  leave  the  same  borders  on  the  right  and 
left  edges  of  active  graphics  that  a  true  CGA  or  EGA  adapter  would  leave.  If 
emulations!),  then  the  graphics  from  a  VGA  adapter  cover  the  entire  width 
of  the  background  video.  (See  Appendix  A  for  more  information  on  graphics 
registration  and  VGA  emulation  of  CGA  and  EGA  graphics.) 

Issuing  vmSetGraphics  emulationsO  on  a  true  CGA  or  EGA-based  system 
returns  error  194  (Unsupported  graphics  mode). 

Gmode  parameter  The  gmode  parameter  sets  the  graphics  display  mode  in  accordance  with 
IBM  graphics  mode  numbers  as  returned  by  BIOS  interrupt  10H,  service 
OFH  (see  Appendix  B).  This  parameter  places  mode  changes  under  VDI  Man¬ 
agement  control  to  keep  screen  disruption  to  a  minimum  (as  opposed  to  using 
mode  functions  furnished  separately  with  development  systems). 

Requesting  an  unsupported  graphics  mode  returns  error  194  (Unsupported 
graphics  mode). 

Width  parameter  The  width  parameter  sets  the  total  graphics  width  in  microseconds.  This  pa¬ 
rameter  lets  applications  accurately  establish  the  right-hand  edge  of  the  ac¬ 
tive  graphics  area  relative  to  background  video.  An  application  would 
typically  display  a  videodisc  position-reference  frame  for  interactively  setting 
width.  (See  Appendix  A  for  more  information  on  graphics  registration.) 


Width  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). 


The  xoffset  and  yoffset  parameters  set  the  offset  of  the  upper  left  comer  of 
the  graphics  display  area  relative  to  video.  These  parameters  shift  the  entire 
graphics  display  area  up,  down,  left,  and  right  within  the  video  raster  in  one- 
pixel  increments.  Positive  values  shift  down  and  right;  negative  values  shift 
up  and  left.  (See  Appendix  A  for  default  offsets  by  graphics  mode.) 

Offset  values  are  absolute,  not  cumulative.  Issuing  vmSetGraphics 
yoffset«4  twice  results  in  an  offset  of  four,  not  eight.  Values  that  exceed  the 
maximum  that  a  system  can  shift  the  graphics  plane  result  in  the  maximum 
possible  shift. 

The  offset  values  set  by  vmSetGraphics  remain  in  effect  until  explicitly 
reset  by  vmSetGraphics  or  vmlnit.  They  do  not  change  to  compensate  for 
graphics  mode  changes.  Therefore,  apparent  offsets  may  change  with  graph¬ 
ics  mode  changes  because  of  differences  in  pixel  sizes  among  modes. 


Xoffset  and 

yoffset 

parameters 
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Notes 


Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Set  X  and  Y  off¬ 
sets  to  -1  and  5 

Set  graphics 
mode  16  (EGA 
640x350) 

Binary 

Shift  graphics 
right  one  and 
down  two 


After  return 


April  15, 1990 


vmSetGraphics 


1.  vmGetState  returns  the  current  X  and  Y  offsets.  These  values  will  not 
agree  with  the  values  set  by  vmSetGraphics  if  the  specified  values  ex¬ 
ceed  the  maximum  amount  the  system  can  shift  the  graphics  plane. 

2.  The  xoffset  and  yoffset  parameters  are  for  correcting  graphics  registra¬ 
tion  to  video.  Applications  should  not  use  them  for  special  effects  such  as 
scrolling  the  screen  because  they  may  cause  screen  disturbances. 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 

vmGetState,  vmlnit. 


vmSetGraphics  xoffset=-l,yoffset=5 
(returns)  “OK” 

vmSetGraphics  gmode=16 
(returns)  “OK” 


AX 

2062 

;  vmSetGraphics  decimal  ID 

BX 

2 

;  number  of  parameters 

ES:DI[0] 

60 

;  xoffset  decimal  ID 

ES:DI[4] 

1 

;  pixel  offset  value 

ES:DI[8] 

66 

;  yoffset  decimal  ID 

ES:DI[C] 

2 

;  pixel  offset  value 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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vmSetPalette 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

color 

Core 

Logical  color 
number 

Integer 

None 

N/A 

Causes 

error 

r 

Core 

Red  value,  0-255 

Integer 

None 

N/A 

No  action 

g 

Core 

Green  value,  0-255 

Integer 

None 

N/A 

No  action 

b 

Core 

Blue  value,  0-255 

Integer 

None 

N/A 

No  action 

Exactly  one  color  and  at  least  one  of  r,  g.  and  b  are  required  or  an  error  is  returned. 


Binary 

Command  code:  2063  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

color 

Core 

9 

Integer 

Logical  color 
number 

None 

Causes 

error 

r 

Core 

38 

Integer 

Red  value,  0-255 

None 

No  action 

g 

Core 

25 

Integer 

Green  value, 

0-255 

None 

No  action 

b 

Core 

4 

Integer 

Blue  value,  0-255 

None 

No  action 

1  length 

Core 

31 

Integer 

Number  of  color 
array  entries1 

None 

No  action 

larray 

Core 

1 

Pointer 

Pointer  to  color 
array 

None 

No  action 

|  Either  exactly  one  color  and  at  least  one  of  r,  g,  and  b  are  required;  or  color, 
Jand  array  must  be  used  together  without  r,  g,  or  b;  or  an  error  is  returned. 

ength, 

’color  array  entry  *  4  bytes  comprised  of  3  components  +  reserved  byte. 
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Description 

Summary 

General 

discussion 


Color  +  r,  g,  and 
b  parameters 


vmSetPalette 


vmSetPalette  assigns  red,  green,  and  blue  component  values  to  the  speci¬ 
fied  logical  color  via  the  ASCII  interface  or  to  one  or  more  contiguous  logical 
colors  via  the  binary  interface. 


vmSetPalette  sets  the  proportions  of  the  red,  green,  and  blue  components  in 
a  logical  color  as  real  numbers  in  the  range  0-255  where  255  is  fully  satu¬ 
rated.  Component  values  are  set  for  single  colors  via  the  ASCII  interface  and 
for  single  or  multiple  colors  via  the  binary  interface  depending  on  the  calling 
parameters. 


vmGetState  logcolors  returns  the  number  of  available  logical  colors  (colors 
that  can  be  simultaneously  displayed)  for  a  system  and  vmGetState 
physcolors  returns  the  number  of  available  physical  colors  (palette  size). 
vmSetPalette  assigns  physical  colors  to  logical  colors  and  vmGetPalette  re¬ 
turns  the  component  values  for  the  assigned  colors.  For  example,  a  system 
might  support  16  logical  colors  from  a  palette  of  4096  physical  colors.  Logical 
color  3  might  be  bright  cyan  with  component  values  of  r=0,  b=255,  g=255. 


These  parameters  apply  to  both  the  ASCII  and  binary  interfaces.  The  color 
parameter  defines  the  logical  color  number  for  which  r,  g,  and  b  component 
values  are  set.  Logical  color  numbers  range  from  zero  to  the  value  returned 
by  vmGetState  logcolors  minus  one. 


VDI  Management  maps  the  specified  component  levels  to  the  color  as  closely 
as  possible  given  the  size  of  the  available  palette.  For  example,  if  the  palette 
furnishes  four  color  levels  (0,  85, 170,  and  255)  for  each  component  (64-color 
palette),  vmSetPalette  color*l,r»110  results  in  a  mapped  value  of  r=85. 


Exactly  one  color  parameter  must  be  listed.  Specifying  color  twice  causes  er¬ 
ror  54  (Parameter  used  more  than  once)  while  omitting  color  entirely  or  fail¬ 
ing  to  include  at  least  one  of  r,  g,  and  b  causes  error  49  (Insufficient 
parameters).  Any  or  all  of  r,  g,  and  b  can  be  specified  in  the  same  call. 
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vmSetPalette 

Color  +  length 
and  array 
parameters 


Notes 


Returns 

ASCII 

Binary 


The  length  and  array  parameters  are  available  with  the  binary  interface 
only.  They  provide  a  way  to  pass  a  pointer  to  an  array  for  storing  a  set  of  pal¬ 
ette  values  in  application  memory.  The  value  associated  with  array  is  a  32- 
bit  pointer  to  a  memory  block  containing  one  or  more  4-byte  structures. 

Array  must  point  to  memory  allocated  by  the  application.  The  contents  of 
each  structure  in  the  palette  array  are: 

•  Byte  0,  the  least  significant  byte,  represents  blue. 

•  Byte  1  represents  green. 

•  Byte  2  represents  red. 

•  Byte  3  is  reserved  and  must  be  set  to  zero. 

The  length  parameter  specifies  the  number  of  4-byte  structures  in  the  array. 
The  values  in  the  first  structure  of  the  array  are  for  the  logical  color  specified 
by  the  color  parameter.  The  second  structure  relates  to  color+1,  the  third  to 
color+2,  an  so  on  up  to  the  number  of  structures  specified  by  length.  (See 
Section  4.4.2  for  more  information  about  color  arrays.) 

Using  the  length  and  array  with  any  of  r,  g,  or  b  causes  error  50  (Parame¬ 
ters  cannot  be  used  together). 

1.  Use  syQueue  to  set  multiple  logical  colors  in  the  same  vertical  interval  via 
the  ASCII  interface. 

2.  Component  values  returned  by  vmGetPalette  may  not  agree  exactly  with 
values  set  by  vmSetPalette  because  of  rounding.  For  example,  a  system 
with  4  levels  per  component  (0, 85, 170, 255)  will  return  a  component 
value  of  85  even  though  the  value  specified  by  vmSetPalette  was  55. 

3.  VDI  Management  does  not  maintain  palette  arrays  that  are  directly  acces¬ 
sible  by  applications.  Palette  arrays  for  vmSetPalette  must  be  allocated 
by  the  application.  To  allocate  memory  in  bytes  for  a  palette  array,  use 

length  x  4. 

4.  If  a  vmSetPalette  is  used  with  palette  array  and  queued  with  syQueue, 
do  not  deallocate  the  array  before  executing  the  queue. 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 
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See  also: 


Examples 


ASCII 

Set  red  to  63  for 
color  0,  do  not 
change  other 
components 

Set  color  1  to  pure 
fully  saturated 
blue 

Set  color  2  to 
bright  white 


Binary 

Set  green  to  127 
for  color  3,  do  not 
change  other 
components 


After  return 

Set  component 
values  for  colors 
3-9 


After  return 


vmSetPalette 


syQueue,  vmGetPalette,  vmGetState. 


vmSetPalette  color=0,r=63 
(returns)  “OK” 


vmSetPalette  color=l,r=0,g=0,b=255 
(returns)  “OK” 


vmSetPalette  color=2,r=255,g=255,b=255 
(returns)  “OK” 


AX 

2063 

;  vmSetPalette  decimal  ID 

BX 

2 

;  number  of  parameters 

ES:DI[0] 

9 

;  color  decimal  ID 

ES:DI[4] 

3 

;  color  number 

ES:DI[8] 

25 

;  g  decimal  ID 

ES:DI[C] 

127 

;  green  value 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

AX 

2063 

;  vmSetPalette  decimal  ID 

BX 

3 

;  number  of  parameters 

ES:DI[0] 

9 

;  color  decimal  ID 

ES:DI[4] 

3 

;  first  color  of  array  list 

ES:DI[8] 

31 

;  length  decimal  ID 

ES:DI[C] 

7 

;  number  of  color  structures  in  palette  array 

ES:DI[10] 

1 

;  array  decimal  ID 

ES:DI[14] 

pointer 

;  pointer  to  palette  array  in  application  memory 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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vmSetTrans 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

clear 

Core 

None 

N/A 

None 

N/A 

No  action 

color 

Core 

Logical  color 
number 

Integer 

None 

N/A 

No  action 

enable 

Core 

1  (on)  |  0  (off) 

Integer 

None 

N/A 

No  action 

state 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

Either  both  color  and  state,  or  clear  only  must  be  used  or  an  error  is  returned.  Enable 
can  be  used  alone  or  with  a  color  +  state. 


Binary 

Command  code:  2064  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

clear 

Core 

8 

N/A 

None 

None 

No  action 

color 

Core 

9 

Integer 

Logical  color 
number 

None 

No  action 

enable 

Core 

20 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

|  state 

Core 

42 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

Either  both  color  and  state,  or  clear  only  must  be  used  or  an  error  is  returned.  Enable 
can  be  used  alone  or  with  a  color  +  state. 


Description 

Summary  vmSetTrans  sets  logical  colors  to  transparent  or  opaque  and  turns  physical 

transparency  on  and  off. 

Clear  The  clear  parameter  sets  the  transparency  state  of  all  logical  colors  to  zero 

(off).  Note  that  this  not  only  turns  transparency  off  but  also  changes  the  val¬ 
ues  of  color  attributes.  Use  the  enable  parameter  (see  below)  to  turn  trans¬ 
parency  off  without  changing  the  transparency  settings  of  the  colors. 
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Color  and  state 
parameters 


Enable  parameter 


Notes 


vmSetTrans 


Using  vmSetTrans  clear  when  no  transparent  colors  are  set  does  nothing 
and  is  not  an  error.  Using  clear  with  any  other  parameter  returns  error  50 
(Parameters  cannot  be  used  together). 


The  color  and  state  parameters  work  together  to  set  logical  colors  to  opaque 
or  transparent.  vmSetTrans  colordlogical  color  number),  state=l 
makes  colors  transparent;  vmSetTrans  color=(logical  color  number), 
stated)  makes  colors  opaque.  To  temporarily  override  transparent  colors, 
use  the  enable  parameter  (see  below). 


The  enable  parameter  controls  physical  transparency  on  the  display  screen. 
vmSetTrans  enabled  makes  all  designated  transparent  colors  actually  be¬ 
come  transparent  to  the  video  plane.  Areas  containing  transparent  colors  on 
the  screen  show  the  video  plane  only. 


vmSetTrans  enable=0  makes  all  colors  physically  opaque  regardless  of 
their  transparency  settings.  None  of  the  video  plane  is  visible.  However, 
transparent  colors  keep  their  transparency  settings  and  will  again  be  physi¬ 
cally  transparent  after  a  subsequent  vmSetTrans  enabled. 


Enable  can  be  combined  with  a  color  and  a  state  to  specify  a  transparent 
color  and  turn  transparency  on  with  the  same  command.  The  default  for 
enable  after  a  vmlnit  is  zero  (transparency  off). 


1.  vmGetState  logcolors  returns  the  total  number  of  available  logical  colors. 
vmGetState  color  returns  the  transparency  setting  for  a  single  specified 
color. 

2.  vmGetState  transcolors  returns  the  number  of  logical  colors  that  can  be 
made  transparent.  Using  vmSetTrans  to  try  to  set  more  than  trans¬ 
colors  to  transparent  returns  error  51  (Parameter  invalid  or  out  of  range). 


Compliant  systems  must  support  transparency  tor  at  least  one  color  that  can  be 
assigned  to  any  logical  color.  Applications  striving  tor  maximum  portability  should 
not  assume  more  than  one  transparent  color. 
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vmSetTrans 


Returns 

ASCII 


Binary 


See  also: 


Examples 

ASCII 

Set  color  0  to 
transparent  and 
enable  physical 
transparency 

Set  color  5  to 
opaque 

Set  all  colors  to 
opaque 

Binary 

Designate  color  3 
as  transparent 
and  make  It 
physically 
transparent 


After  return 

Make  all  colors 
opaque 


After  return 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 

vmGetState. 


vmSetTrans  color=0,state=l,enable=l 
(returns)  “OK” 


vmSetTrans  color=5,state=0 
(returns)  “OK” 

vmSetTrans  clear 
(returns)  “OK” 


AX 

2064 

;  vmSetTrans  decimal  ID 

BX 

3 

;  number  of  parameters 

ES:DI[0] 

9 

;  color  decimal  ID 

ES:DI[4] 

3 

;  color  number 

ES:DI[8] 

42 

;  state  decimal  ID 

ES:DI[C] 

1 

;  make  color  3  transparent 

ES:DI[10] 

20 

;  enable  decimal  idea 

ES:DI[14] 

1 

;  turn  physical  transparency  on 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

AX 

2064 

;  vmSetTrans  decimal  ID 

BX 

1 

;  number  of  parameters 

ES:DI[0] 

8 

;  clear  decimal  ID 

ES:DI[4] 

any  value 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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vmSetVideo 


Current:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

defsource 

Core 

Input  source,  0-15 

Integer 

None 

N/A 

No  action 

vmode 

Core 

0  (native)  1 1  (NTSC) 

|  2  (PAL) 

Integer 

None 

N/A 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


Binary 

Command  code:  2065  decimal. 


|  Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

Idefsource 

Core 

13 

Integer 

Input  source,  0-15 

None 

No  action 

1  vmode 

Core 

53 

Integer 

0  (native)  1 1  (NTSC) 

|  2  (PAL) 

None 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned. 


Description 

Summary  vmSetVideo  sets  the  video  mode  and  selects  the  video  input  source  if  more 

than  one  source  is  available. 


Defsource  The  defsource  parameter  selects  a  video  input  source  in  the  range  0  to  15 

parameter  when  more  than  one  video  source  is  available.  The  default  at  start-up  is 

source  zero. 


Vmode  parameter  The  vmode  parameter  tells  the  visual-management  system  which  video  stan¬ 
dard  incoming  video  and  the  monitor  are  using.  This  lets  VDI  Management 
use  the  appropriate  timing  values  for  the  standard.  Vmode«l  sets  NTSC- 
U.S.;  vmode*2  sets  PAL-European.  vmSetVideo  vmode»0  (native)  sets  the 
system  to  the  functionality  and  appearance  that  the  computer  would  use  if  it 
were  not  an  IV  system.  This  setting  also  turns  overlay  off  without  affecting 
any  other  parameters  relating  to  overlay. 
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vmSetVideo 

vmSetVideo  vmode...  may  cause  screen  disturbances  because  of  the  asyn 
chrortous  rates  of  the  graphics  and  video  signals. _ 


Notes  1.  A  video  source  is  always  selected,  but  the  source  number  will  not  neces- 

"  sarily  equal  the  current  default  player  number.  For  example,  logical 

player  zero  may  be  logical  video  source  one.  This  mapping  is  done  at  VDI 
installation/configuration  time.  (See  Section  4.1.2  for  more  information.) 

2.  After  a  player  is  selected  with  vdSet  defdevice  (see  Section  8),  it  must  be 
activated  as  a  video  source  with  vmSetVideo  defsource. 

Returns 

ASCII  On  success:  “OK”. 

On  failure:  “ERROR  n...“. 

Binary  On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


See  also:  vdSet,  vmGetState. 


Examples 

ASCII 

Set  the  standard  vmSetVideo  vmode=  1 

to  NTSC  (returns)  “OK” 

Make  video  vmSetVideo  defsource=  1 

source  one  the  (returns)  “OK” 

default 

Binary 

Set  mode  to  NTSC  AX  2065  ;  vmSetVideo  decimal  command  ID 

BX  1  ;  number  of  parameters 

ES:DI[0]  53  ;  vmode  decimal  ID 

ES:DI(4]  1  ;  sets  mode  to  NTSC  (1) 

After  return  AX  0  ;  returns  0  if  successful  (nonzero  if  not) 
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This  section  describes  commands  that  control  videodisc  players.  Use  these 
commands  to  initialize,  obtain  information  about,  and  control  the  behavior  of 
videodisc  players  connected  to  the  system.  Table  8-1  lists  the  commands  cov¬ 
ered  in  this  section,  their  token  numbers,  and  their  types. 


Table  8-1. 
Videodisc  command 
names,  token 
numbers,  and  types 


ASCII  command 
name1 

Binary  interface 
token  number 
(decimal) 

Type2 

vdGetState 

3078 

Core 

vdlnit 

3079 

Core 

vdPassThru 

3080 

Core 

vdPlay 

3081 

Core  j 

vdScan 

3083 

Core 

vdSearch 

3084 

Core 

vdSet 

3085 

Core 

vdStep 

3090 

Core 

vdStill 

3091 

Core 

1  Upper  or  tower  case  for  command  names  is  not  significant. 
Compliant  implementations  must  support  “Core'  commands. 


8.1  Genera!  information  and  assumptions 


The  general  information  and  assumptions  given  in  this  subsection  were  used 
in  the  definition  of  the  videodisc  commands. 

8.1 .1  CAV  and  CLV  videodisc  support _ 

Current  technology  uses  two  types  of  videodiscs — constant  angular  velocity 
(CAV)  and  constant  liner  velocity  (CLV).  These  vary  in  the  information  sup¬ 
plied  on  the  videodisc  and  the  way  in  which  they  are  read.  The  individual 
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command  descriptions  indicate  commands  and  parameters  that  apply  to  CLV 
videodiscs  only. 

Current  support  for  CLV  videodiscs  is  a  subset  of  CAV  functions.  We  do  not 
rule  out  adding  extended  commands  and  parameters  to  provide  more  sophisti¬ 
cated  CLV  support  in  future  revisions  of  this  document. 


Compliant  players  must  support  both  CAV  and  CLV  videodiscs. 


8.1 .2  Play  and  scan  speeds 


Play  speeds  are  expressed  as  a  multiples  of  1.0,  which  is  defined  as  the  nor¬ 
mal  speed  of  either  25  frames  per  second  for  PAL  or  30  frames  per  second  for 
NTSC.  For  players  in  CAV  mode,  applications  can  assume  that  speed  1.0,  at 
least  one  speed  slower  than  1.0,  and  at  least  one  speed  faster  than  1.0  are 
available.  For  players  in  CLV  mode,  applications  cannot  assume  play  speeds 
other  than  1.0.  (Section  8.2  explains  how  VDI  Managements  round  speeds 
when  requested  speeds  cannot  be  matched  exactly  by  a  player.) 


Scan  speeds  vary  among  players.  All  an  application  can  assume  about  a  scan 
speed  is  that  it  is  faster  than  normal  speed. 


Note:  Because  applications  cannot  assume  that  values  other  than  1.0  will  be 
matched  exactly,  they  should  not  try  to  calculate  videodisc  position  based  on 
timing  and  frame  speed  at  any  speed  other  than  1.0.  Instead,  they  should  use 
vdGetState  frame  (see  vdGetState  command). 


8.1 .3  Searches  and  instant  jumps 


When  searching  for  a  specific  frame  or  chapter,  players  should  use  instant 
jumps  if  possible.  If  not,  the  search  should  always  be  at  the  fastest  possible 
speed.  Blanking  during  searches  is  automatic  and,  therefore,  is  not  under 
VDI  Management  control. 


8.1 .4  Fields,  frames,  and  chapters 


All  frame  numbers  assume  a  standard  format  of  two  fields  per  frame.  The 
command  set  does  not  support  accessing  individual  fields.  The  command  set 
assumes  that  frame  numbers  are  always  available  from  CAV  and  never  from 
CLV  and  that  chapter  numbers  may  be  available  from  either. 
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8.2  Rounding  methods  for  player  speeds 


Player  speeds  are  represented  by  real  numbers,  with  1.0  representing  normal 
speed.  Values  below  1.0  represent  speeds  below  normal;  values  above  1.0  rep¬ 
resent  speeds  above  normal.  A  value  other  than  1.0  calls  for  a  speed  in 
frames  per  second  (fps)  that  equals  the  product  of  the  value  and  the  default 
number  of  frames  per  second.  For  example,  on  an  NTSC  system,  a  speed  of 
0.5  specifies  a  rate  of  0.5  x  30  fps  or  15  fps. 

Videodisc  players  are  usually  limited  to  a  finite  range  of  speeds.  If  a  re¬ 
quested  speed  is  not  1.0,  VDI  Management  uses  a  rounding  algorithm  to 
translate  from  the  specified  speed  to  a  player-supported  speed.  The  algorithm 
rounds  to  the  nearest  supported  speed,  except  that  values  are  never  rounded 
to  0.0  or  1.0  except  for  players  in  CLV  mode  (see  below).  This  method  lets  ap¬ 
plications  guarantee  use  of  the  fastest  fast  and  slowest  slow  speeds  available. 
The  following  tables  show  how  speeds  are  rounded  for  the  Sony  2000  and  Pio¬ 
neer  4200,  respectively.  Note  that  speed  requests  of  0.0  are  errors. 


Table  8~2. 
The  effects  of 
rounding  on  speed 
parameters  for  the 
Sony  2000 


Requested 

speed 

Actual  speed 
as  multiple  of 
normal 

0.0 

Error 

0.00001-0.99999 

0.2 

1.0 

1.0 

1 .00001  and  up 

3 

Table  8^3. 
The  effects  of 
rounding  on  speed 
parameters  for  the 
Pioneer  4200 


Requested 

speed 

Actual  speed 
as  multiple  of 
normal 

0.0 

Error 

0.00001-0.14999 

0.1 

0.15-0.34999 

0.2  | 

0.35-0.64999 

0-5  | 

0.65-0.99999 

0.8  1 

1.0 

1 

1.0001-2.4999 

2  j 

2.5-3.4999 

3 

3.5  and  up 

4 

For  players  in  CAV  mode,  applications  can  assume  that  normal  speed,  1.0,  at 
least  one  speed  slower  than  1.0,  and  at  least  one  speed  faster  than  1.0  are 
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available.  Given  this  availability  and  the  rounding  algorithm,  which  never 
rounds  to  0.0  or  1.0,  the  following  table  lists  speed  parameter  values  for  speci¬ 
fying  several  convenient  speeds  without  knowing  the  exact  speeds  available 
from  a  given  player. 


Table  8-4. 
Example  speed 
parameter  values  for 
boundary  player 
speeds 


Speed  parameter  value 

Resulting  player  speed 

0.0 

Error 

0.00001 

Slowest  available  speed 

0.99999 

Fastest  speed  that  is  slower  than  normal 

1.00001 

Slowest  speed  that  is  faster  than  normal 

9999 

Fastest  available  speed 

For  players  in  CLV  mode,  applications  cannot  assume  play  speeds  other  than 
normal  speed.  For  players  that  support  normal  speed  only,  all  speeds  other 
than  zero  are  rounded  to  one.  However,  if  the  player  supports  multiple 
speeds  in  CLV  mode,  VDI  Management  applies  normal  rounding  rules. 

Note:  After  requesting  a  play  speed,  a  query  for  that  speed  returns  the  actual 
speed  if  it  differs  from  the  requested  speed  because  of  rounding. 
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vdGetState 


Last  revision:  R  1 .0 
Type:  core 


Parameters 


ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

audiol 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

audio2 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

cdisplay 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

chapter 

Core 

None 

N/A 

Current  chapter 
number 

Integer 

No  action 

defdevice 

Core 

None 

N/A 

Default  player, 
0-15 

Integer 

No  action 

device 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

disctype 

Core 

None 

N/A 

1  (CLV)  1 0  (CAV) 

Integer 

No  action 

door 

Extended 

None 

N/A 

1  (open)  | 

0  (closed) 

Integer 

No  action 

mm 

Core 

None 

N/A 

Current  frame 
number 

Integer 

No  action 

Idxdisplay 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

motion 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

remote 

Extended 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

speed 

Core 

None 

N/A 

Current  player 
speed  or  999  if 
scanning 

Real 

No  action 

spin 

Core 

None 

N/A 

1  (up)  1 0  (down) 

Integer 

No  action 

tdevices 

Core 

None 

N/A 

Total  installed  for, 
0-15 

Integer 

No  action 

video 

Core 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

At  least  one  parameter  must  be  specified  or  an  error  occurs.  If  device  is  specif 
least  one  other  parameter  must  be  specified. 

ed,  at  I 

1  Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs. 
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vdGetState 

Binary 

Command  code:  3078  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

audiol 

Core 

2 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

audio2 

Core 

3 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

cdisplay 

Core 

6 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

chapter 

Core 

■ 

Integer 

Any  value 

Current  chapter 
number 

No  action 

defdevice 

Core 

12 

Integer 

Any  value 

Default  player, 
0-15 

No  action 

device 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

disctype 

Core 

16 

Integer 

Any  value 

1  (CLV)  1 0  (CAV) 

Extended 

18 

Integer 

Any  value 

1  (open)  | 

0  (closed) 

No  action 

frame1 

Core 

23 

Integer 

Any  value 

Current  frame 
number 

No  action 

idxdisplay 

Core 

29 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

motion 

Core 

35 

Integer 

Any  value 

1  (on)  |  0  (off) 

No  action 

remote 

Extended 

39 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

speed 

Core 

40 

Real 

Any  value 

Current  player 
speed  or  999  if 
scanning 

No  action 

Core 

41 

Integer 

Any  value 

1  (up)  1 0  (down) 

No  action 

tdevices 

Core 

45 

Integer 

Any  value 

Total  installed 
for,  0-15 

No  action 

video 

Core 

51 

Integer 

Any  value 

1  (on)  1 0  (off) 

No  action 

At  least  one  parameter  must  be  specified  or  an  error  occurs.  If  device  is  specified,  at 
least  one  other  parameter  must  be  specified. 


1  Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs. 


8-6 


Release  R  1.0 


April  15, 1990 


Section  8.  Videodisc  commands  (yd) 


Description 

Summary 


Audiol  and 

audio2 

parameters 


Cdisplay 

parameter 


Chapter 

parameter 


Defdevice 

parameter 


Device  parameter 


Disc  type 
parameter 


vdGetState 


vdGetState  returns  information  about  the  videodisc  player  specified  by  the 
device  parameter  or  the  default  player  if  no  device  number  is  specified. 


The  audiol  and  audio2  parameters  return  one  if  the  respective  audio  chan¬ 
nel  is  on  and  zero  if  it  is  off. 


The  cdisplay  parameter  returns  one  if  the  player’s  chapter  number  display 
is  on  and  zero  if  it  is  not.  Using  cdisplay  with  videodiscs  that  do  not  have 
chapter  numbers  returns  error  88  (Unable  to  return  requested  information). 


The  chapter  parameter  returns  the  current  videodisc  chapter  number. 
vdGetState  chapter...  returns  error  86  (Device  not  ready)  if  the  videodisc  is 
not  spinning  normally  and  error  88  (Unable  to  return  requested  information) 
if  the  videodisc  does  not  have  chapter  numbers. 


The  defdevice  parameter  returns  the  default  logical  player  number  as  set  by 
vdSet  defdevice  or  vdlnit.  VDI  Management  directs  all  videodisc  com¬ 
mands  to  this  player  unless  a  command  contains  a  device  parameter  (see 
below)  directing  it  to  a  different  player. 


The  device  parameter  directs  vdGetState  to  the  specified  logical  player 
number  regardless  of  the  current  player  number  as  set  by  vdSet  defdevice. 
Because,  in  general,  device  affects  the  command  with  which  it  is  associated 
only,  the  parameter  does  not  affect  the  return  value  for  defdevice  (see 
above)  when  the  two  parameters  are  used  together. 


Specifying  device  with  no  other  parameter  returns  error  49  (Insufficient  pa¬ 
rameters).  Specifying  a  nonexistent  or  uninstalled  player  returns  error  160 
(Invalid  device  number).  Specifying  an  uninitialized  player  returns  error  81 
(Device  not  initialized). 


The  disctype  parameter  returns  one  if  the  videodisc  is  a  CLV  disc  and  zero  if 
it  is  a  CAV  disc. 
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vdGetState 

Door  parameter 


Frame  parameter 

Idxdisplay 

parameter 

Motion  parameter 

Remote  parameter 

Speed  parameter 

Spin  parameter 

Tdevices 

parameter 


The  door  parameter  returns  one  if  the  player  door  is  open  and  zero  if  it  is 
closed.  VDI  implemented  should  implement  door  for  a  player  that  supports 
reporting  the  door’s  status  even  if  the  player  does  not  support  opening  and 
closing  the  door  from  an  application.  If  an  implementation  supports  the  door 
parameter  but  a  player  does  not  support  reporting  its  status,  VDI  Manage* 
ment  returns  error  88  (Unable  to  return  requested  information). 


Door  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). _ 


The  frame  parameter  returns  the  current  frame  number  of  the  videodisc 
player.  vdGetState  frame...  returns  error  86  (Device  not  ready)  if  the 
videodisc  is  not  spinning  normally.  Frame  returns  error  88  (Unable  to  return 
requested  information)  for  CLV  discs. 

The  idxdisplay  parameter  returns  one  if  player’s  frame  number  (CAV)  or 
time  (CLV)  display  is  on  and  zero  if  it  is  not. 


The  motion  parameter  returns  the  state  of  a  background  play  or  scan.  If  the 
laser  is  reading  the  videodisc  during  a  play  or  scan  sequence  either  backward 
or  forward,  motion  returns  one;  otherwise,  it  returns  zero. 

The  remote  parameter  returns  one  if  the  player’s  remote  control  unit  is  on 
and  zero  if  it  is  off.  If  a  VDI  implementation  supports  the  remote  parameter 
but  the  player  does  not  support  a  remote  control  unit,  remote  returns  zero. 


Remote  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). _ _ 


The  speed  parameter  returns  the  actual  player  speed  after  any  necessary 
rounding  or  999  if  the  player  is  in  scan  mode.  A  return  of  zero  indicates  the 
player  is  parked  or  on  a  still  frame.  (See  Section  8.2  for  information  on 
rounding  speed  values.) 

The  spin  parameter  returns  zero  if  the  player  is  parked  or  one  if  the 
videodisc  is  spinning  and  the  player  is  ready  to  accept  motion  commands. 

The  tdevices  parameter  returns  the  total  number  of  logical  players  for  which 
VDI  Management  was  configured  when  it  was  installed.  If  only  one  player  is 
connected,  it  is  numbered  zero,  and  tdevices  returns  one. 


8-8 


Release  R  1.0 


April  15, 1990 


Section  8.  Videodisc  commands  (vd) 


Video  parameter 


Parameters 
resulting  in  errors 


Notes 


Returns 

ASCII 


Binary 


See  also: 


Examples 

ASCII 

Get  status  of 
player  2  motion 
flag 

Get  information 
on  door  and  spin 
state  for  current 
player 


vdGetState 


The  video  parameter  returns  one  if  the  player’s  video  channel  is  on  and  zero 
if  it  is  not. 

If  a  parameter  causes  an  error,  vdGetState  returns  immediately  with  the 
error  message.  The  command  does  not  return  partial  responses  for  other  pa¬ 
rameters  that  did  not  cause  errors. 


1.  vdGetState  can  be  successfully  issued  any  time  VDI  Management  can  ac¬ 
cept  commands.  The  current  state  of  the  player  does  not  affect  whether 
the  command  can  be  issued.  However,  the  player’s  state  can  affect  the  abil¬ 
ity  to  return  specific  parameter  values, and  therefore  cause  errors.  For  ex¬ 
ample,  vdGetState  frame  returns  error  88  (Unable  to  return  requested 
information)  if  the  player  is  parked. 

2.  Trying  to  queue  vdGetState  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 


On  success:  Comma-separated  list  of  values  for  requested  parameters  as  de¬ 
scribed  above. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0.  Values  associated  with  requested  parameters  are  32-bit 
values  of  the  types  given  in  the  binary  parameter  table  above. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


syGetState,  vdlnit,  vdSet,  vmGetState,  xyGetState. 


vdGetState  device=2,  motion 

(returns)  “1"  ;  player  2  is  in  play  or  scan  mode 


vdGetState  door, spin 

(returns)  “1,0”  ;  door  is  open  and  player  is  spun  down 
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vdGetState 


Get  whether  disc 
Index  display  is 
on  for  current 
player 

vdGetstate  idxdisplay 
(returns)  “1” 

;  videodisc  index  display  is  on 

Get  whether 
player  1  video  Is 
on  and  currently 
selected  player 

vdGetState  device=l, video, defdevice 

(returns)  “1,2”  ;  player  1  video  is  on, 

;  default  player  is  logical  number  2 

Binary 

Get  status  of 
motion  flag 

AX  3078 

BX  1 

ES:DI(0]  35 

ES:DI[4]  any  value 

;  vdGetstate  decimal  ID 
;  number  of  parameters 
;  motion  decimal  ID 

;  place  holder  for  motion  value  after  return 

After  return 

AX  0 

ES:DI[4]  1 

;  returns  0  if  successful  (nonzero  if  not) 

;  value  for  motion,  player  is  playing  or  scanning 
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vdlnit 


Last  Revision:  R  1 .0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  If 
parameter 
not  used 

device1 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

(This  command  can  be  issued  with  no  parameters.  j 

1This  parameter  applies  to  both  CAV  and  CLV  videodiscs  as  does  vdlnit  with  no 
parameters. 


Binary 

Command  code:  3079  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If 
parameter 
not  used 

device1 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

This  command  can  be  issued  with  no  parameters. 


1This  parameter  applies  to  both  CAV  and  CLV  videodiscs  as  does  vdlnit  with  no 
parameters. 


Description 

Summary  vdlnit  initializes  videodisc  hardware  and  the  vd  software  service  group,  plac¬ 

ing  both  in  a  known  state,  vdlnit  must  be  issued  for  each  attached  player 
that  will  be  used  by  the  application.  This  command  interrupts  any  other 
player  motion  command  that  did  not  include  a  wait  parameter,  in  which 
case,  the  application  will  not  be  able  to  issue  vdlnit  until  the  motion  com¬ 
mand  is  complete. 

vdlnit  is  a  synchronous  command.  It  does  not  return  control  to  the  applica¬ 
tion  until  it  has  succeeded  or  detected  an  error  condition.  To  keep  distur¬ 
bances  to  a  minimum,  VDI  Management  should  turn  video  and  audio  oft  at 
the  player,  spin  up  the  videodisc,  then  turn  video  and  audio  back  on. 
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vdlnit 


Device  parameter 


Conditions  set  by 
vdlnit 


Notes 


The  resulting  display  after  vdlnit  varies  with  videodisc  type.  With  CAV 
videodiscs,  video  remains  visible  with  the  player  frozen  on  the  first  available 
frame.  With  most  CLV  videodiscs,  the  player  automatically  blanks  video. 

The  device  parameter  specifies  the  logical  player  number  to  be  initialized.  If 
device  is  omitted,  vdlnit  initializes  the  default  player  as  set  by  vdSet 
defdevice.  If  vdSet  has  not  been  used  to  set  a  default  player,  the  default 
player  is  defined  to  be  number  zero,  vdlnit  does  not  change  the  default 
player  if  a  device  other  than  the  default  is  specified.  To  change  the  default, 
use  vdSet  defdevice. 

Specifying  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  de¬ 
vice  number). 

vdlnit  sets  the  parameters  in  the  following  table  to  the  specified  values. 


|  Parameter  values  set  by  vdlnit  jj 

Parameter 

Value 

Command  reference 

audiol 

1  (on) 

vdSet 

audio2 

1  (on) 

vdSet 

cdisplay 

0  (oil)  or  undelined 

vdSet 

door1 2 3 

0  (closed) 

vdSet 

frame 

First  available  on  disc 

vdPlay,  vdSet 

idxdisplay 

0  (off) 

vdSet 

motion 

0  (off) 

vdGetState 

remote1 

0  (Off) 

vdSet 

spin 

1  (up) 

vdSet 

tdevices 

Total  installed,  0-15 

none 

video 

1  (on) 

vdSet 

supported  by  implementation— this  is  an  extended  parameter. 


1.  vdlnit  can  be  successfully  issued  any  time  the  specified  device  or,  without 
a  specified  device,  the  default  player,  either  player  zero  or  the  player  set  by 
vdSet  defdevice,  can  accept  motion  commands  (except  see  Note  4  below). 

2.  vdGetState  tdevices  returns  the  total  number  of  players  for  which  VDI 
Management  was  installed.  This  command  can  be  used  after  the  first  vdlnit 
to  determine  the  number  of  additional  devices  that  can  be  initialized. 

3.  If  the  player  supports  a  character  generator,  vdlnit  turns  it  off. 
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Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Initialize  player  0 
and  vd  service 
group 

Initialize  player  1 


vdlnit 


4.  Trying  to  queue  vdlnit  causes  error  177  (Command  cannot  be  queued)  at 
the  time  of  the  attempt. 

5.  With  systems  that  do  not  support  the  door  parameter,  VDI  Management 
returns  error  80  (Initialization  error)  if  an  application  issues  vdlnit  with  the 
player  door  open.  Therefore,  it  is  good  programming  practice  to  prompt  the 
user  to  insert  the  videodisc  and  close  the  door  before  issuing  vdlnit. 

6.  Spinning  the  videodisc  up  also  updates  the  disctype  parameter,  and  sets 
cdisplay  to  undefined  for  videodiscs  that  do  not  support  chapter  numbers. 

7.  If  vdlnit  returns  an  error,  the  parameters  listed  in  the  table  above  have  un¬ 
defined  values. 


On  success:  “OK”. 

On  failure:  “ERROR  n...” 


On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


sylnit,  vdGetstate,  vdSet,  vmlnit,  xylnit. 


vdlnit 

(returns)  “OK”  ;  first  time  command  is  issued 


vdlnit  devices  1 
(returns)  “OK” 
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vdlnit 


Binary 


Initialize  player  0 

AX 

3079 

and  vd  service 

BX 

0 

group 

After  return 

AX 

0 

Initialize  player  1 

AX 

3079 

BX 

1 

ES:DI[0] 

14 

ES:DI[4) 

1 

After  return 

AX 

0 

;  vdlnit  decimal  ID 
;  number  of  parameters 

;  returns  0  if  successful  (nonzero  if  not) 

;  vdlnit  decimal  ID 
;  number  of  parameters 
;  device  decimal  ID 
;  logical  player  number  for  device 

;  returns  0  if  successful  (nonzero  if  not) 
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vdPassThru 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII  No  named  parameters  (see  discussion  of  device  and  pmsg  parameters 

below).  Applies  to  both  CAV  and  CLV  videodiscs. 


Binary 

Command  code:  3080  decimal. 


Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

device 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

pmsg 

Core 

37 

Pointer 

Pointer  to  player 
message  string 

Player  response 
string 

This  command  must  be  issued  with  the  pmsg  parameter  or  an  error  is  returnee 

l  1 

1  All  parameters  apply  to  both  CAV  and  CLV  videodiscs. 


Description 

Caution 


vdPassThru  is  provided  to  allow  nonportable  access  to  special  features  of 
videodisc  players.  It  Is  Included  to  as  a  convenience  to  developers  who  want 
to  use  the  command  set  for  portable  applications  and  do  not  want  to  switch 
to  a  different  command  environment  for  development  efforts  that  require 
access  to  nonportable  player  functions  that  are  not  provided  by  other 
commands  in  the  videodisc  service  group.  Therefore,  although  It  is  re¬ 
quired,  it  is  supplied  for  convenience  only  and  SHOULD  NOT  be  used  for 
developing  portable  applications. 


Summary  vdPassThru  communicates  directly  with  a  player,  bypassing  the  standard 

videodisc  service  group  commands  and  parameters.  It  is  provided  to  allow  ac¬ 
cess  to  specific  player  features  that  are  not  supported  by  other  VDI  videodisc 
commands.  vdPassThru  passes  an  string  of  printable  ASCII  characters  to 
the  player  and  waits  for  the  player’s  response.  This  response  is  returned  to 
the  application.  vdPassThru  does  not  return  application  control  until  it  re¬ 
ceives  a  response  from  the  player  or  detects  an  error. 
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vdPassThru 

Device  parameter  The  device  parameter  directs  vdPassThru  to  the  specified  logical  player 
number  regardless  of  the  default  player  number  as  set  by  vdSet  defdevice. 
This  parameter  applies  to  the  binary  interface  only. 

Specifying  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  de¬ 
vice  number).  Specifying  an  uninitialized  player  causes  error  81  (Device  not 
initialized). 

The  ASCII  interface  does  not  accept  a  device  parameter  because  of  potential 
difficulties  in  distinguishing  the  parameter  label  and  associated  value  from 
the  string  that  should  be  passed  to  the  player.  Therefore,  the  ASCII  interface 
always  sends  the  command  string  to  the  default  player.  (To  set  the  default 
player,  see  the  vdSet  command.) 

Pmsg  parameter  The  pmsg  parameter  value  is  a  series  of  printable  ASCII  characters  to  be 

passed  through  to  the  player  without  modification  by  VDI  Management.  How¬ 
ever,  implementors  may  need  to  implement  VDI  Management  so  that  it  sup¬ 
plies  a  specific  terminator  if  required  by  a  specific  supported  player. 

The  binary  interface  passes  a  pointer  to  a  null-terminated  player  message 
string.  For  the  ASCII  interface,  all  characters  from  the  delimiter  following 
the  “u”  in  vdPassThru  up  to  the  terminating  CR  make  up  the  message 
string.  The  ASCII  interface  does  not  use  a  pmsg  parameter  label. 


Returns 

ASCII  On  success:  Player  response  +  CR/LF  if  CR/LF  is  not  automatically  returned 

by  the  player. 

On  failure:  “ERROR  n. . 

Binary  On  success:  AX  =  0.  String  pointed  to  by  the  pmsg  parameter  contains  the 

player  response  +  NULL. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


Examples 

ASCII 


Send  a  string  to  the  player 
vdPassThru  THIS  IS  A  COMMAND 

(returns)  "THIS  IS  A  PLAYER  RESPONSE” 
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vdPassThru 


Binary 


Send  a  command 

AX 

3080 

string  to  player  2 

BX 

2 

ES:DI[0] 

14 

ES:DI[4] 

1 

ES:DI[8] 

37 

ES:DI[C3 

pointer 

After  return 

AX 

0 

ES:DI[C] 

pointer 

vdPassThru  decimal  ID 

number  of  parameters 

device  decimal  ID 

send  message  to  player  1 

pmsg  decimal  ID 

pointer  to  player  message  string 

returns  0  if  successful  (nonzero  if  not) 
pointer  to  player  response  string 
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vdPlay 


Last  revision:  R  1 .0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling  value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  If 
parameter 
not  used 

chapter 

Core 

Chapter  number 

Integer 

None 

N/A 

No  action 

device 

Core 

Logical  player,  0-15 

Integer 

None 

N/A 

Default 

player 

isEsaai 

Core 

1  (fwd)  1 0  (back) 

Integer 

None 

N/A 

1 

Core 

Starting  frame  number 

Integer 

None 

N/A 

Current 

frame 

speed 

Core 

Play  speed,  >0 

Real 

None 

N/A 

1.0 

to1 

Core 

Ending  frame  number 

Integer 

None 

N/A 

Disc  limit 

wait 

Core 

None 

N/A 

None 

N/A 

No  wait 

(This  command  may 

ae  issued  with  no  parameters. ' 

rhe  text  describes 

llegal  usage.  f 

1  Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs  as  does  vdPlay  with  no  parameters. 


Binary 

Command  code:  3081  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

chapter 

Core 

7 

Integer 

Chapter  number 

None 

No  action 

device 

Core 

14 

Integer 

Logical  player, 

0-15 

None 

Default 

player 

direction1 

Core 

15 

Integer 

1  (fwd)  1 0  (back) 

None 

1 

from1 

Core 

24 

Integer 

Starting  frame 
number 

None 

Current 

frame 

speed 

Core 

40 

Real 

Play  speed,  >0 

Actual  speed  after 
rounding  if  required 

1.0 

to1 

Core 

48 

Integer 

Ending  frame 
number 

None 

Disc  limit 

wait 

Core 

54 

N/A 

None 

None 

No  wait 

|This  command  may 

be  issuec 

with  no  parameters.  The  text  describes  illegal  usage.  f 

1  Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs  as  does  vdPlay  with  no  parameters. 
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vdPlay 

Description 

Summary  vdPlay  executes  videodisc  play  sequences.  The  sequences  may  include  start¬ 

ing  frames,  ending  frames,  chapters,  directions,  and  speeds  in  various  combi¬ 
nations.  The  application  can  instruct  VDI  Management  to  return  control 
immediately  or  when  the  play  sequence  is  complete.  This  command  inter¬ 
rupts  any  other  player  motion  command  that  did  not  include  a  wait  parame¬ 
ter,  in  which  case,  the  application  will  not  be  able  to  issue  vdPlay  until  the 
motion  command  is  complete. 

No  parameters  vdPlay  issued  with  no  parameters  causes  the  player  to  start  playing  forward 
from  the  current  frame  at  a  speed  of  1.0  and  continues  until  interrupted  by  a 
subsequent  vdlnit,  vdPlay,  vdScan,  vdSearch,  vdSet  spin=down, 
vdStep,  or  vdStill  command,  or  until  the  player  reaches  the  end  of  the 
videodisc. 

Chapter  The  chapter  parameter  specifies  a  chapter  number  to  play  from  beginning  to 

parameter  end.  When  used  with  a  speed  parameter,  the  chapter  plays  at  the  specified 

speed.  Adding  wait  causes  VDI  Management  to  wait  to  return  application 
control  until  the  chapter  has  been  played. 

Specifying  a  chapter  for  a  videodisc  without  chapter  numbers  causes  error 
208,  (Action  not  supported  by  disc).  Specifying  an  illegal  chapter  number 
causes  error  216  (Invalid  chapter  number). 

Compatible  parameters— device,  speed,  and  wait.  Other  parameters 
cause  error  50  (Parameters  cannot  be  used  together). 

Device  parameter  The  device  parameter  directs  vdPlay  to  the  specified  logical  player  number 
regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Specify¬ 
ing  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device  num¬ 
ber);  specifying  an  uninitialized  player  causes  error  81  (Device  not  initialized). 

Compatible  parameters — all,  assuming  other  parameters  are  compatible 
with  each  other. 

Direction  The  direction  parameter  sets  the  direction  of  motion  (1  =  forward,  0  =  back- 

parameter  ward)  for  play  sequences  that  do  not  include  to  frames.  Specifying  a  direc¬ 

tion  with  no  from  frame  or  chapter  starts  a  play  sequence  in  the  specified 
direction  from  the  current  frame  at  an  optional  speed.  If  a  from  frame  is 
specified,  the  player  searches  to  the  specified  frame,  then  begins  play  in  the 
specified  direction.  Specifying  a  direction  with  a  chapter  is  discussed 
above  (see  the  chapter  parameter  above). 
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vdPlay 


From  parameter 


Speed  parameter 


Specifying  a  direction  with  a  to  frame  causes  error  50  (Parameters  cannot 
be  used  together)  because  the  direction  required  to  reach  the  to  frame  is  pre¬ 
determined  either  by  the  relative  position  of  the  current  frame  or,  if  specified, 
the  relative  position  of  the  from  frame.  Therefore,  a  direction  used  with  a 
to  frame  is  at  best  redundant  if  it  agrees  with  the  predetermined  direction, 
and  at  worst  conflicting  if  it  opposes  the  predetermined  direction. 

Compatible  parameters — from,  device,  speed,  and  wait.  Other  parame¬ 
ters  cause  error  50  (Parameters  cannot  be  used  together). 

The  from  parameter  specifies  the  starting  frame  number  for  a  play  sequence. 
The  player  immediately  searches  or  jumps  to  the  specified  frame  with  video 
off,  turns  video  on,  and  executes  the  play  sequence  at  an  optional  speed  and 
either  to  an  optional  to  frame  OR  in  an  optional  direction.  Note  that 
vdPlay  from=1000,  to=1000  is  exactly  the  same  as  vdSearch  frames 1000. 

A  from  parameter  with  no  to  parameter  starts  an  unbounded  play.  The  play 
sequence  continues  until  interrupted  by  another  vdPlay,  or  a  vdlnit, 
vdScan,  vdSearch,  vdSet  spin«down,  vdStep,  or  vdStill  command,  or 
until  the  player  reaches  the  edge  of  the  videodisc. 

Specifying  a  from  frame  for  a  CLV  videodisc  causes  error  208,  (Action  not 
supported  by  disc).  Specifying  an  illegal  frame  number  causes  error  215  (In¬ 
valid  frame  number). 

Compatible  parameters — device,  direction  OR  to,  speed,  and  wait. 
Other  parameters  or  illegal  combinations  of  compatible  parameters  cause 
error  50  (Parameters  cannot  be  used  together). 

The  speed  parameter  specifies  the  speed  of  play.  VDI  Management  maps  re¬ 
quested  speeds  as  closely  as  possible  to  available  player  speeds.  Because  ac¬ 
tual  speeds  may  vaiy  from  requested  speeds,  the  binary  interface  changes 
the  speed  value  passed  in  the  parameter  block  to  the  actual  speed  set  by  VDI 
Management  and  vdGetState  speed  returns  the  actual  speed  after  any  nec¬ 
essary  rounding.  For  CAV  mode,  speeds  are  never  rounded  to  zero  or  one. 
(See  Section  8.2  for  detailed  information  on  rounding  speed  values  including 
boundary  conditions.) 

Specifying  a  speed  less  than  or  equal  to  zero  causes  error  51  (Parameter 
value  invalid  or  out  of  range). 

Compatible  parameters— device,  direction  OR  to,  from,  chapter  but 
not  with  from  or  to,  and  wait.  Other  parameters  or  illegal  combinations  of 
compatible  parameters  cause  error  50  (Parameters  cannot  be  used  together). 
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To  parameter 


Wait  parameter 


vdPlay 

The  to  parameter  specifies  the  ending  frame  number  for  a  play  sequence. 
When  tiie  player  reaches  the  to  frame,  the  player  automatically  enters  still 
mode  displaying  the  frame. 

The  to  parameter  has  lower  priority  than  the  from  parameter.  For  example, 
vdPlay  fro m= 100,  to=1000  and  vdPlay  to=1000,  from=100  both  search  to 
frame  100,  then  play  to  frame  1000. 

Specifying  a  to  frame  for  a  CLV  videodisc  caused  error  208,  (Action  not  sup¬ 
ported  by  disc).  Specifying  an  illegal  frame  number  causes  error  215  (Invalid 
frame  number).  Specifying  a  to  frame  with  a  direction  is  covered  above  (see 
Direction  parameter). 

Compatible  parameters — device,  from,  speed,  and  wait.  Other  parame¬ 
ters  cause  error  50  (Parameters  cannot  be  used  together). 

The  effect  of  the  wait  parameter  depends  on  the  parameters  that  accompany 
it.  The  following  table  lists  when  vdPlay  wait...  returns  application  control 
based  on  accompanying  parameters.  Obviously,  if  the  player  returns  an  error, 
the  command  will  return  when  the  error  state  is  detected  instead  of  at  the 
time  given  in  the  table. 


Effects  of  wait  on  vdPlay 

Additional  parameter 

Returns  control  when? 

none 

After  the  default  player  is  playing  normally 

chapter 

After  the  player  has  played  the  specified  chapter 

device  only 

After  the  specified  player  is  playing  normally 

from  with  any  other  legal 
parameters  except  to 

After  the  player  has  searched  to  the  specified  from 
frame 

speed  only 

After  the  player  is  playing  normally  at  the  specified 

speed 

to  with  any  other  legal 
parameters 

After  the  player  reached  the  specified  to  frame 

Without  wait,  VD1  Management  returns  control  as  soon  as  it  determines 
that  the  command  is  legal.  No  error  checking  is  done  to  determine  if  the 
player  actually  accepts  the  command  or  acts  on  it  properly.  Therefore, 
syCheckErr  must  be  used  to  determine  if  the  player  entered  an  error  state 
while  either  accepting  or  trying  to  execute  the  command. 
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vdPlay 


Notes 

Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Play  forward  at 
speed  1.0  from 
current  frame 


syCheckErr  may  also  be  needed  to  detect  certain  error  states  that  occur 
after  vdPlay  wait.  For  example,  vdPlay  wait,  from=1000  returns  when 
the  from  frame  has  been  reached.  syCheckErr  is  required  to  detect  any 
error  state  that  occurs  after  the  player  has  reached  frame  1000. 

Note  that  without  wait,  a  subsequent  vdPlay,  vdlnit,  vdScan,  vdSearch, 
vdSet  spin* down,  vdStep  or  vdStill  command  immediately  interrupts  an 
executing  play  sequence,  even  if  the  play  sequence  specifies  a  target — either 
a  to  frame  or  the  end  of  a  chapter. 

Compatible  parameters — all,  assuming  other  parameters  are  compatible 
with  each  other. 


1.  vdPlay  can  be  successfully  issued  any  time  spinel  (up)  as  set  by  vdSet. 

2.  vdGetState  motion  can  be  used  to  find  out  whether  the  player  is  cur¬ 
rently  executing  a  play  sequence.  This  could  be  used,  for  example,  with  a 
vdPlay  to...  with  no  wait  parameter  to  determine  whether  the  to  frame 
has  been  reached. 

3.  All  parameters  apply  to  the  current  vdPlay  only.  For  example,  vdPlay 
to=1000,  speed =.5  does  not  set  the  speed  to  a  default  of  0.5.  A  subsequent 
vdPlay  without  a  speed  will  play  at  speed  1.0,  not  0.5. 


On  success:  “OK”. 

On  failure:  “ERROR  n. 

On  success:  AX  =  0.  Value  associated  with  speed  parameter  is  a  32-bit  real 
that  gives  the  actual  speed  that  will  be  set  after  rounding  if  required. 

On  failure:  AX  =  error  number. 

syCheckErr,  vdGetState,  vdScan,  vdSearch  vdStep,  vdStill. 


vdPlay 

(returns)  “OK” 
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vdPlay 


Play  backward 
from  frame  1000 
at  the  slowest  pos¬ 
sible  speed 


vdPlay  speed=.00001,direction=0,from=1000 
(returns)  “OK” 


Play  from  current 
frame  to  2000, 
don’t  return  until 
it  is  reached 


vdPlay  to=2000,wait 
(returns)  “OK” 


Play  backward  to 
frame  1 


vdPlay  to=l,direction=0 

(returns)  “ERROR  50”;  Parameters  cannot  be  used  together 


Play  backward 
from  200  to  100 


vdPlay  from=200,to=100 
(returns)  “OK” 


or 

vdPlay  to=100,from=200 
(returns)  “OK” 


Play  backward 
from  the  current 
frame 


vdPlay  direction=0 
(returns)  “OK” 


Play  all  of  chapter  vdPlay  chapter=2 
2  at  speed  1.0  (retums)“OK” 


Binary 


Play  from  frame 

AX 

3081 

200  to  500 

BX 

2 

ES:DI[0] 

24 

ES:DI[4] 

200 

ES:DI[8] 

48 

ES:DI[C] 

500 

After  return 

AX 

0 

;  vdPlay  decimal  ID 
;  number  of  parameters 
;  from  decimal  ID 
;  starting  frame  number 
;  to  decimal  ID 
;  ending  frame  number 

;  returns  0  if  successful  (nonzero  if  not) 
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vdScan 


Last  revision:  R  1 .0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

device 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

Core 

1  (fwd)  1 0  (back) 

Integer 

None 

N/A 

1 

1  waft 

Core 

None 

N/A 

None 

N/A 

No  wait 

|This  command  may  be 

ssued  with  no  parameters.  | 

’Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs  as  does  vdScan  with  no  parameters. 


Binary 

Command  code:  3083  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If 
parameter 
not  used 

device 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

direction1 

Core 

15 

Integer 

1  (fwd)  1 0  (back) 

None 

1 

wait 

Core 

54 

N/A 

None 

None 

No  wait  | 

This  command  may  be  issued  with  no  parameters. 


’Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV 
videodiscs  as  does  vdScan  with  no  parameters. 


Description 

Summary  vdScan  places  the  default  or  specified  player  in  scan  mode  in  an  optional  di¬ 

rection.  The  player  plays  at  the  maximum  possible  speed.  The  command  con¬ 
tinues  until  interrupted  by  a  subsequent  vdPlay,  vdlnit,  vdScan, 
vdSearch,  vdSet  spin-down,  vdStep,  or  vdStill  command,  or  until  the 
player  reaches  the  edge  of  the  videodisc.  This  command  interrupts  any  other 
player  motion  command  that  did  not  include  a  wait  parameter,  in  which 
case,  the  application  will  not  be  able  to  issue  vdScan  until  the  motion  com¬ 
mand  is  complete. 
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No  parameters 
Device  parameter 

Direction 

parameter 

Wait  parameter 

Notes 

Returns 

ASCII 

Binary 

See  also: 


vdScan 


vdScan  with  no  parameters  starts  scanning  forward  from  the  current  frame. 


The  device  parameter  directs  vdScan  to  the  specified  logical  player  number 
regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Specify¬ 
ing  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device  num¬ 
ber).  Specifying  an  uninitialized  player  causes  error  81  (Device  not 
initialized). 


The  direction  parameter  sets  the  direction  of  motion  for  the  scan,  either  one 
(forward)  or  zero  (backward). 


The  wait  parameter  causes  VDI  Management  to  wait  until  it  has  confirmed 
that  the  player  is  in  scan  mode  to  return  application  control.  Without  wait, 
VDI  Management  returns  control  as  soon  as  it  determines  that  the  command 
is  legal.  No  error  checking  is  done  to  determine  if  the  player  actually  accepts 
the  command  or  acts  on  it  properly.  Therefore,  syCheckErr  must  be  used  to 
determine  if  the  player  entered  an  error  state  while  either  accepting  or  trying 
to  execute  the  command. 


1.  Because  vdScan  often  results  in  displaying  parts  of  frames  and  does  not  ac¬ 
cept  parameters  to  limit  the  area  of  the  videodisc  that  is  scanned,  the  com¬ 
mand  is  typically  used  during  application  development  only. 


On  success:  “OK”. 

On  failure:  “ERROR  n...” 


On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


vdPlay,  vdlnit,  vdScan,  vdSearch,  vdSet,  vdStep,  vdStill. 
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vdScan 

Examples 

ASCII 

Scan  forward  vdScan 

from  the  current  (returns)  “OK* 

frame 

Scan  backward  on  vdScan  direction=0,device=l,wait 
player  1 ,  do  not  (returns)  “OK” 

return  until  scan 
mode  Is  confirmed 

Binary 


Scan  backward  on 

AX 

3083 

;  vdScan  decimal  ID 

the  default  player 

BX 

2 

;  number  of  parameters 

ES:DI[0] 

15 

;  direction  decimal  ID 

ES:DI[4] 

0 

;  direction  in  which  to  play  (backward) 

After  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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vdSearch 


Last  revision:  R  1 .0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

chapter 

Core 

Chapter  number 

Integer 

None 

N/A 

No  action 

device 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

frame1 

Core 

Frame  number 

Integer 

None 

N/A 

No  action 

wait 

Core 

None 

N/A 

None 

N/A 

No  wait 

This  command  must  include  a  chapter  or  frame  or  an  error  is  returned.  If  device  or 
wait  is  specified,  at  least  one  other  parameter  must  be  specified. 

1  Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV. 


Binary 

Command  code:  3084  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If  I 
parameter 
not  used 

chapter 

Core 

7 

Integer 

Chapter  number 

None 

No  action 

device 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

frame1 

Core 

23 

Integer 

Frame  number 

None 

No  action 

wait 

Core 

54 

N/A 

None 

None 

No  wait 

This  command  must  include  a  chapter  or  frame  or  an  error  is  returned.  If  device  or 
wait  is  specified,  at  least  one  other  parameter  must  be  specified. 


Supported  for  CAV  videodiscs  only.  All  other  parameters  apply  to  both  CAV  and  CLV. 


Description 

Summary  vdSearch  causes  the  player  to  turn  video  off,  immediately  search  for  the 

specified  frame  number  or  the  first  frame  of  the  specified  chapter  number, 
and  freeze.  This  command  interrupts  any  other  player  motion  command  that 
did  not  include  a  wait  parameter,  in  which  case,  the  application  will  not  be 
able  to  issue  vdSearch  until  the  motion  command  is  complete. 
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vdSearch 

Chapter 

parameter 

Device  parameter 

Frame  parameter 

Wait  parameter 

Returns 

ASCII 

Binary 

See  also: 


The  resulting  display  after  vdSearch  varies  with  videodisc  type.  With  CAV 
videodiscs,  video  remains  visible.  With  most  CLV  videodiscs,  vdSearch  is 
equivalent  to  searching  to  the  start  of  a  chapter  followed  by  a  pause  com¬ 
mand.  Typically,  a  CLV  pause  command  automatically  blanks  video. 

The  chapter  parameter  specifies  a  chapter  number  to  search  to.  The  player 
displays  the  first  frame  of  the  specified  chapter  (CAV)  or  pauses  and  blanks 
video  (CLV). 

Specifying  a  chapter  for  a  videodisc  without  chapter  numbers  causes  error 
208,  (Action  not  supported  by  disc).  Specifying  an  illegal  chapter  number 
causes  error  216  (Invalid  chapter  number). 

The  device  parameter  directs  vdSearch  to  the  specified  logical  player  num¬ 
ber  regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Spec¬ 
ifying  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device 
number;  specifying  an  uninitialized  player  causes  error  81  (Device  not 
initialized). 

The  frame  parameter  specifies  a  frame  number  to  search  to.  The  player  dis¬ 
plays  the  specified  frame. 

Specifying  a  frame  for  a  CLV  videodisc  causes  error  208,  (Action  not  sup¬ 
ported  by  disc).  Specifying  an  illegal  frame  number  causes  error  215  (Invalid 
frame  number). 

The  wait  parameter  causes  VDI  Management  to  wait  until  the  specified 
chapter  or  frame  has  been  reached  to  return  application  control.  Without 
wait,  VDI  Management  returns  control  as  soon  as  it  determines  that  the  com¬ 
mand  is  legal.  No  error  checking  is  done  to  determine  if  the  player  actually  ac¬ 
cepts  the  command  or  acts  on  it  properly.  Therefore,  syCheckErr  must  be 
used  to  determine  if  the  player  entered  an  error  state  while  either  accepting 
or  trying  to  execute  the  command. 


On  success:  “OK”. 

On  failure:  “ERROR  n..." 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 

vdPlay,  vdSet,  vdStep,  vdStill. 
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vdSearch 


Examples 


ASCII 


Search  for  frame  vdSearch  frame=23476 

23476  (returns)  “OK” 


Search  for  vdSearch  chapter=5, devices  1, wait 

chapter  5  on  (returns)  “OK” 

player  1,  do  not 
return  until  the 
chapter  has  been 
reached 


Binary 


Search  for  frame 

AX 

3084 

10356 

BX 

1 

ES:DI[0] 

23 

ES:DI[4] 

10356 

After  return 

AX 

0 

;  vdSearch  decimal  ID 
;  number  of  parameters 
;  frame  decimal  ID 
;  frame  number  for  which  to  search 

;  returns  0  if  successful  (nonzero  if  not) 
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vdSet 

Parameters 

ASCII 


Parameter1 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

audiol 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

audio2 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

cdispiay 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

defdevice 

Core 

Logical  player,  0-15 

Integer 

None 

N/A 

No  action 

device 

Core 

Logical  player,  0-15 

Integer 

None 

N/A 

Default 

player 

door 

Extended 

1  (open)  1 0  (closed) 

Integer 

None 

N/A 

No  action 

idxdisplay 

Core 

1  (on)  ( 0  (off) 

Integer 

None 

N/A 

No  action 

remote 

Extended 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

spin 

Core 

1  (up)  1 0  (down) 

Integer 

None 

N/A 

No  action 

video 

Core 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

wait 

Core 

None 

N/A 

None 

N/A 

no  wait 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  or  wait  is  specified, 
at  least  one  other  parameter  must  be  specified.  _  _ 


’All  parameters  apply  to  both  CAV  and  CLV. 


Last  revision:  R  1 .0 
Type:  core 
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vdSet 


Binary 

Command  code:  3085  decimal. 


Parameter1 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

audiol 

Core 

2 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

audio2 

Core 

3 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

cdisplay 

Core 

6 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

defdevlce 

Core 

12 

Integer 

Logical  player,  0-15 

None 

No  action 

device 

Core 

14 

Integer 

Logical  player,  0-15 

None 

Default 

player 

door 

Extended 

18 

Integer 

1  (open)  1 0  (closed) 

None 

No  action 

idxdisplay 

Core 

29 

Real 

1  (on)  1 0  (off) 

None 

No  action 

remote 

Extended 

39 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

spin 

Core 

41 

Integer 

1  (up)  1 0  (down) 

None 

No  action 

video 

Core 

51 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

wait 

Core 

54 

N/A 

None 

None 

No  wait 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  or  wait  is  specified, 
at  least  one  other  parameter  must  be  specified. 


’ah  parameters  apply  to  both  CAV  and  CLV. 


Description 


Summary 


Audiol  and 

audio2 

parameters 


Cdisplay 

parameter 


vdSet  sets  the  default  logical  player  number  and  other  player  conditions  in¬ 
cluding  the  state  of  the  audio  and  video  channels,  the  frame  and  chapter  num¬ 
ber  displays,  the  disc  spin/park  status,  whether  the  door  is  open  or  closed, 
and  whether  the  user  remote  control  is  on  or  off. 

The  audiol  and  audio2  parameters  enable  and  disable  the  player’s  stereo 
outputs.  Setting  both  audiol  and  audio2  to  zero  turns  off  all  player  audio. 


Note:  Many  players  automatically  route  the  output  of  an  enabled  audio  chan¬ 
nel  to  a  disabled  channel.  For  example,  if  audiol  >0  and  audio2*l,  the 
player  may  automatically  route  the  output  of  audio2  to  audiol. 

The  cdisplay  parameter  enables  and  disables  the  player’s  chapter-number 
display.  This  display  is  typically  a  character  generator  within  the  videodisc 
player  that  displays  chapter-number  information  as  part  of  the  video  signal. 
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vdSet 

Defdevlce 

parameter 


Device  parameter 


Door  parameter 


Idxdisplay 

parameter 


Remote  parameter 


Spin  parameter 


The  defdevice  parameter  sets  the  default  logical  player  number.  VDI  Man¬ 
agement  directs  all  videodisc  commands  to  this  player  number  unless  a  com¬ 
mand  contains  a  device  parameter  (see  below)  directing  it  to  a  different 
player  number. 

The  device  parameter  directs  vdSet  to  the  specified  logical  player  number 
regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Specify¬ 
ing  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device  num¬ 
ber);  specifying  an  uninitialized  player  causes  error  81  (Device  not  initialized). 

The  door  parameter  opens  and  closes  the  videodisc  player  door.  If  the  player 
does  not  support  this  function,  the  parameter  returns  error  87  (Action  not 
supported  by  device).  VDI  implementers  should  implement  door  for  a  player 
that  supports  reporting  the  door’s  status  even  if  the  player  does  not  support 
opening  and  closing  the  door  from  an  application. 


Door  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). _ _ I 


The  idxdisplay  parameter  enable  and  disable  the  player’s  position  index  dis¬ 
play.  The  resulting  display  is  in  frame  numbers  for  CAV  videodiscs  and  time 
for  CLV  videodiscs.  This  display  is  typically  a  character  generator  within  the 
videodisc  player  that  displays  videodisc  position  as  part  of  the  video  signal. 

The  remote  parameter  turns  the  hand  held  remote  on  and  off.  Remote*0 
(off)  gives  the  application  software  complete  control  over  the  videodisc  player. 
If  the  player  does  not  support  this  function,  remote  returns  error  87  (Action 
not  supported  by  device). 


Remote  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). 


The  spin  parameter  spins  the  disc  up  and  down.  Spin*l  (up)  causes  the 
player  to  spin  up  and  still  on  frame  1  (or  the  first  available  frame).  Spinning 
the  videodisc  up  also  updates  the  disctype  parameter,  and  sets  cdisplay  to 
undefined  for  videodiscs  that  do  not  support  chapter  numbers. 

Spin*0  (down)  causes  the  player  to  spin  down  immediately,  interrupting  any 
player  motion  command  not  accompanied  by  the  wait  parameter,  in  which 
case,  the  application  will  not  be  able  to  issue  vdSet  spin*0  until  the  motion 
command  is  complete. 
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Video  parameter 
Wait  parameter 


Notes 

Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Turn  off  both 
number  displays 

Disable  hand-held 
remote  control  on 
player  1 

Make  logical 
player  1  the 
default 

Turn  on  all  player 
outputs 


vdSet 


The  video  parameter  enables  and  disables  the  player’s  video  output  channel. 

With  the  wait  parameter,  vdSet  does  not  return  application  control  until  the 
specified  settings  have  been  acknowledged  or  a  player  error  state  is  detected. 
Without  wait,  VDI  Management  returns  control  as  soon  as  it  determines 
that  the  command  is  legal.  No  error  checking  is  done  to  determine  if  the 
player  actually  accepts  the  command  or  acts  on  it  properly.  Therefore, 
syCheckErr  must  be  used  to  determine  if  the  player  entered  an  error  state 
while  either  accepting  or  trying  to  execute  the  command. 

Specifying  wait  with  no  other  parameter  results  in  error  49  (Insufficient 
parameters). 


1.  vdSet  can  be  successfully  issued  any  time  the  player  can  accept  commands, 
except  that  vdSet  door»l  (open)  can  be  issued  only  when  spin*0  (down) 
and  the  player  has  actually  completed  the  spin  down  sequence. 


On  success:  “OK”. 

On  failure:  “ERROR  n...". 

On  success:  AX  =  0. 

On  failure:  Ax  =  error  number. 

syCheckErr,  vdGetState. 


vdSet  idxdisplay=0,cdisplay=0 
(returns)  “OK” 

vdSet  remote=0, device= 1 
(returns)  “OK" 


vdSet  defdevice=l 
(returns)  “OK” 


vdSet  videos  l,audiols  l,audio2s  1 
(returns)  “OK” 
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vdSet 

Disable  audio 
channel  1 

Binary 

Turn  on  player 
index  display 


After  return 

Set  video  on, 
audio  channel  1 
on,  audio 
channel  2  off 


After  return 


vdSet  audiol=0 
(returns)  “OK” 


AX 

3085 

BX 

1 

ES:DI[0] 

29 

ES:DI[4] 

1 

AX 

0 

AX 

3085 

BX 

3 

ES:DI[0] 

51 

ES:DI[4] 

1 

ES:DI[8] 

2 

ES:DI[C] 

1 

ES:DI[10] 

3 

ES:DI[14] 

0 

AX 

0 

vdSet  decimal  ID 
number  of  parameters 
idxdisplay  decimal  ID 
set  value  to  1  (on) 

returns  0  if  successful  (nonzero  if  not) 

vdSet  decimal  ID 
number  of  parameters 
video  decimal  ID 
set  value  to  1  (on) 
audiol  decimal  ID 
set  value  to  1  (on) 
audio2  decimal  ID 
set  value  to  0  (off) 

returns  0  if  successful  (nonzero  if  not) 
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vdStep 


Last  revision:  R  1 .0 
Type:  core 


Parameters 

ASCII 


Parameter1 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

device 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

direction 

Core 

1  (fwd)  1 0  (back) 

Real 

None 

N/A 

1 

|This  command  can  be  issued  with  no  parameters. 

’no  parameters  apply  to  CLV  videodiscs,  nor  does  vdStep  alone. 


Binary 

Command  code:  3090  decimal. 


Parameter1 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  If 
parameter 
not  used 

device 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

direction 

Core 

15 

Integer 

1  (fwd)  1 0  (back) 

None 

1 

This  command  can  be  issued  with  no  parameters. 


’No  parameters  apply  to  CLV  videodiscs,  nor  does  vdStep  alone. 


Description 

Summary  vdStep  causes  the  videodisc  player  to  move  forward  or  backward  one  frame 

at  a  time  in  a  specified  direction  without  blanking  the  screen.  The  command 
does  not  return  application  control  until  the  step  is  complete.  This  command 
interrupts  any  other  player  motion  command  that  did  not  include  a  wait  pa¬ 
rameter,  in  which  case,  the  application  will  not  be  able  to  issue  vdPlay  until 
the  motion  command  is  complete. 

No  parameters  With  no  parameters,  vdStep  steps  forward  one  frame  and  freezes. 

Device  parameter  The  device  parameter  directs  vdStep  to  the  specified  logical  player  number 
regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Specify¬ 
ing  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device  num¬ 
ber);  specifying  an  uninitialized  player  causes  error  81  (Device  not  initialized). 
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vdStep 

Direction 

parameter 

Notes 

Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Step  forward  1 
frame 

Step  backward 
one  frame 

Binary  examples 

Step  forward  one 
frame 

After  return 


The  direction  parameter  sets  the  direction  of  motion  for  the  step,  either  one 
(forward)  or  zero  (backward). 


1.  vdStep  can  be  successfully  issued  any  time  the  spin=l  (up)  as  set  by 
vdSet.  However,  issuing  vdStep  while  a  vdPlay  sequence  is  in  progress 
is  not  recommended  because  of  the  difficulty  in  determining  which  frames 
will  be  displayed. 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  Ax=  error  number. 

syCheckerr,  vdPlay,  vdSet. 


vdStep 

(returns)  “OK" 

vdStep  direction=0 
(returns)  “OK” 


AX 

3090 

;  vdStep  decimal  command  ID 

BX 

0 

.  ;  number  of  parameters 

AX 

=  0 

;  returns  0  if  successful  (non-zero  if  not) 
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VdStill  Last  revision:  R  1 .0 

Type:  core 

Parameters 

ASCII  _ 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  If 
parameter 
not  used 

device1 

Core 

Logical  player, 
0-15 

Integer 

None 

N/A 

Default 

player 

|This  command  can  be  issued  with  no  parameters. 

^his  parameter  applies  to  both  CAV  and  CLV  videodiscs  as  does  vdStill  with  no 
parameters. 


Binary 

Command  code:  3091  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

device1 

Core 

14 

Integer 

Logical  player, 
0-15 

None 

Default 

player 

|This  command  can  be  issued  with  no  parameters. 

’This  parameter  applies  to  both  CAV  and  CLV  videodiscs  as  does  vdStill  with  no 
parameters. 


Description 

Summary  vdStill  causes  the  videodisc  player  to  immediately  stop  on  the  current  frame 

and  sets  the  motion  parameter  returned  by  vdGetState  to  zero.  This  com¬ 
mand  interrupts  any  other  player  motion  command  that  did  not  include  a 
wait  parameter,  in  which  case,  the  application  will  not  be  able  to  issue 
vdStill  until  the  motion  command  is  complete. 

The  resulting  display  after  vdStill  varies  with  videodisc  type.  With  CAV 
videodiscs,  video  remains  visible.  With  most  CLV  videodiscs,  vdStill  is  equiv¬ 
alent  to  a  pause  command  and  the  player  automatically  blanks  video. 

Device  parameter  The  device  parameter  directs  vdStill  to  the  specified  logical  player  number 
regardless  of  the  default  player  number  as  set  by  vdSet  defdevice.  Specify¬ 
ing  a  nonexistent  or  uninstalled  player  causes  error  160  (Invalid  device  num¬ 
ber);  specifying  an  uninitialized  player  causes  error  81  (Device  not  initialized). 
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vdStill 

Returns 

ASCII 

Binary 

See  also: 

Examples 

ASCII 

Stop  player  motion 
Binary 

Stop  player  motion 
After  return 


On  success:  “OK”. 

On  failure:  “ERROR  n...”. 

On  success:  AX  =  0. 

On  failure:  Ax=  error  number. 

vdPlay,  vdScan,  vdSet. 


vdStill 

(returns)  “OK” 


AX 

3091 

;  vdStill  decimal  ID 

BX 

0 

;  number  of  parameters 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 
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This  section  describes  commands  that  relate  to  XY-input  devices  such  as 
mice,  touchscreens,  and  light  pens.  These  commands  provide  a  uniform  way 
to  obtain  information  from  these  devices  and  define  coordinate  spaces. 

Table  9-1  lists  the  commands  covered  in  this  section,  their  token  numbers, 
and  their  types. 


Table  9-1. 
XY-input  command 
names,  token 
numbers,  and  types 


1  Upper  or  lower  case  for  command  names  is  not  significant. 
Compliant  implementations  must  support  “Core”  commands. 


ASCII  command 
name1 

Binary  interface 
token  number 
(decimal) 

Type2 

xyGetlnput 

4100 

Core 

xyGetState 

4102 

Core 

xylnit 

4103 

Core 

xySet 

4109 

Core 

9.1  General  information  and  assumptions 


The  general  information  and  assumptions  in  this  subsection  were  used  in  the 
definition  of  the  XY-input  commands. 


9.1 .1  Device  mapping 


Typically,  each  physical  XY-input  device  is  treated  independently  and 
mapped  to  a  unique  logical  device  number.  However,  VDI  implemented  may 
opt  to  support  multiple  physical  devices  as  a  single  logical  device  by  mapping 
the  devices  to  a  single  logical  device  number.  If  so,  VDI  Management  must 
correct  the  raw  values  returned  by  the  physical  devices  so  that  both  devices 
return  the  same  value  for  the  same  screen  position  to  the  application  based 
on  the  application-coordinate  space  established  with  the  xySet  command. 
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All  mapping  must  be  done  when  VDI  Management  is  installed.  Devices  can¬ 
not  be  remapped  at  run-time  and  mapping  is  not  under  application  control. 
Mapping  of  multiple  devices  to  a  single  logical  device  allows  a  user  to  use,  for 
example,  a  mouse  and  a  touchscreen  that  both  appear  to  be  the  same  device 
from  the  application’s  viewpoint. 

Mapping  the  keyboard  or  cursor  keypad  to  an  XY-input  device  is  optional. 

How  such  support  is  provided  is  an  implementation  issue  and  is  not  con¬ 
sidered  by  the  recommended  practices. 

Note  that  the  xy  service  group  keeps  sets  of  all  parameters  that  can  be  re¬ 
turned  by  ryGetlnput  and  xyGetState  for  each  logical  device. 

9.1 .2  Handling  the  graphics  plane  and  cursor _ 

Well  behaved  applications  should  not  turn  off  the  graphics  plane  when  they 
need  selection  and  coordinate  input.  The  plane  must  active  for  a  device  such 
as  a  mouse  to  display  a  cursor  for  making  menu  selections  and  similar  tasks. 

Although  some  XY-input  devices  such  as  touchscreens  allow  input  beyond  the 
limits  of  active  graphics,  applications  should  limit  active  XY-input  areas  to 
the  active  graphics  plane.  Again,  this  is  necessary  for  devices  such  as  mice 
that  rely  on  the  graphics  plane  for  cursor  display. 

The  application  can  determine  if  a  device  supports  a  graphics  c  rsor  with  the 
xyGetState  command.  If  the  device  does  support  a  cursor,  the  application 
should  turn  it  on  for  XY  input. 

9.1 .3  Coordinate  space  mapping _ 

The  alignment  of  specific  XY-coordinate  values  versus  graphics  is  an  imple¬ 
mentation  issue.  However,  the  minimum  and  maximum  values  for  X  and  Y  al¬ 
ways  map  to  the  edges  of  the  active  graphics  area  with  the  upper  left  comer 
of  the  graphics  area  as  the  origin,  which  is  equal  to  xmin  and  ymin. 

For  example,  if  the  minimum  value  for  X  is  0  and  the  maximum  is  10,  these 
map  to  the  left  and  right  edges  of  active  graphics  (typically  0  and  319  or  0 
and  639),  respectively.  If  the  minimum  and  maximum  values  are  -100  and 
-<■100,  these  still  map  to  the  left  and  right  edges  of  active  graphics. 

The  clipping  values  for  X  and  Y  cannot  lie  outside  of  the  minimum  and  maxi¬ 
mum  values.  Trying  to  set  clipping  values  outside  of  the  minimum  and  maxi¬ 
mum  values  causes  an  error. 

For  relative  positioning  devices  such  as  mice,  VDI  Management  ignores 
changes  in  position  which  take  the  cursor  outside  of  the  clipping  area.  For  ab¬ 
solute  positioning  devices  such  as  touchscreens,  VDI  Management  ignores 
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button  presses  outside  of  the  clipping  area.  Application  authors  should  note 
that  the  behavior  differs  between  the  two  device  classes  and  should  consider 
testing  applications  against  both. 

Calibrating  the  XY-coordinate  space  to  the  active  graphics  area  is  an  imple¬ 
mentation  and  application  issue.  Typically,  if  a  device  such  as  a  touchscreen 
requires  calibration,  the  device  comes  with  software  to  support  its  calibration 
at  installation. 

9.1 .4  Buttons 


In  the  context  of  the  XY-command  set,  a  button  is  any  device  that  allows  sig¬ 
naling  the  application  that  a  choice  has  been  made.  A  button  press  may  con¬ 
sist  of  touching  a  finger  to  a  touchscreen  or  pressing  a  physical  button  on  a 
mouse.  The  command  set  supports  devices  with  multiple  buttons.  However, 
applications  should  assume  single-button  devices  for  maximum  portability. 

The  command  set  supports  reporting  only  whether  a  button  has  been 
pressed.  It  does  not  distinguish  touchdown,  liftoff,  or  intensity  (Z  dimension). 
Supporting  these  variations  is  an  application  issue  and  is  nonportable. 

9.2  Stream-mode  and  point-mode  devices 


XY-input  devices  fall  into  two  broad  categories  based  on  how  they  make  posi¬ 
tional  information  available — stream-mode  and  point-mode.  Some  devices 
support  one  mode  only,  while  others  support  both  depending  on  configuration. 

In  stream  mode,  devices  make  position  and  selection  information  available  on 
a  continuous  basis.  Software  can  ask  for  and  receive  current  information  at 
any  time.  In  point  mode,  devices  make  position  and  selection  information 
available  only  when  a  button  is  being  pressed. 

Stream-mode  devices  can  be  forced  into  point  mode  by  restricting  their  func¬ 
tionality.  However,  such  reduced  functionality  would  place  unwarranted  re¬ 
strictions  on  application  design.  Therefore,  VDI  Management  treats  all 
XY-input  devices  as  stream-mode  devices. 

To  treat  both  true  stream-mode  devices  and  point-mode  devices  as  stream¬ 
mode  devices,  the  reported  coordinates  will  be  one  of: 

•  the  current  coordinates  from  a  true  stream-mode  device;  or 

•  the  coordinates  at  the  time  the  button  was  last  pressed  for  a  point-mode 
device;  or 

•  the  minimum  X  and  Y  values  (typically  0,0)  for  a  point-mode  device  for 
which  no  button  has  been  pressed  since  the  device  was  initialized. 
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xyGetlnput 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

buttons 

Core 

None 

N/A 

Integer  sum  of  bit 
field,  1  (closed) 

1 0  (open) 

Integer 

No  action 

device 

Core 

Logical  input 
device,  0-15 

Integer 

None 

N/A 

Default 

device 

xpos 

Core 

None 

N/A 

Current  X  value 

Integer 

No  action 

ypos 

Core 

None 

N/A 

Current  Y  value 

Integer 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  is  specif  ied 
one  other  parameter  must  be  specified. 

,  at  least 

Binary 

Command  code:  4 100  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

buttons 

Core 

5 

Integer 

Any  value 

Bit  field,  1  (closed) 

1 0  (open) 

No  action 

device 

Core 

14 

Integer 

Logical  input 
device,  0-15 

None 

Default 

device 

xpos 

Core 

61 

Integer 

Any  value 

Current  X  value 

No  action 

ypos 

Core 

67 

Integer 

Any  value 

Current  Y  value 

No  action 

[  At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  is  specified,  at  least 
one  other  parameter  must  be  specified. 


Description 

Summary  xyGetlnput  returns  the  current  position  and  button  status  of  the  XY-input 

device. 
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Buttons 

parameter 


Device  parameter 

Xpos  and  ypos 
parameters 

Notes 

Returns 

ASCII 

Binary 


See  also: 


xyGetlnput 

The  button  parameter  returns  the  state  of  all  buttons  as  a  bit  field.  Each  bit 
in  the  bit  field  can  have  two  states — zero  (open)  or  one  (closed).  A  device  can 
have  up  to  32  buttons  numbered  0-31. 

The  binary  interface  returns  a  4-byte  bit  field.  The  least  significant  bit  (bit  0) 
of  the  least  significant  byte  (byte  0)  corresponds  to  button  zero,  the  next  bit  to 
button  one,  and  so  on.  For  example,  if  an  input  device  had  three  buttons  with 
states  of  closed,  open,  closed,  the  binary  interface  would  return  00000101B  in 
the  low  byte. 

The  ASCII  interface  returns  the  same  bit  field  as  an  integer  value.  For  the  ex¬ 
ample  above,  the  ASCII  interfaces  would  return  “5”  (4  +  0  +  1). 

The  device  parameter  directs  xyGetlnput  to  the  specified  logical  XY-input 
device  regardless  of  the  default  device  number  as  set  by  xySet  defdevice. 

Specifying  device  with  no  other  parameter  returns  error  49  (Insufficient  pa¬ 
rameters).  Specifying  a  nonexistent  or  uninstalled  device  returns  error  160 
(Invalid  device  number).  Specifying  an  uninitialized  device  causes  error  81 
(Device  not  initialized). 

The  xpos  and  ypos  parameters  return  the  current  XY  coordinates  of  the  in¬ 
put  device  according  to  the  scale  set  by  xySet. 


1.  xyGetState  tbuttons  returns  the  number  of  buttons  available  on  a  device. 

2.  Trying  to  queue  xyGetlnput  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 


On  success:  Comma-separated  list  of  values  for  requested  parameters  as  de¬ 
scribed  above. 

On  failure:  “ERROR  n...". 

On  success:  AX  =  0.  Values  associated  with  requested  parameters  are  32-bit 
values  of  the  types  given  in  the  binary  parameter  table  above. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


xyGetState,  xySet. 
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xyGetlnput 

Examples 

ASCII 

Get  current  X 
position 

Get  current  XY 
positions  and 
state  of  buttons 

Get  XY  positions 
for  input  device  2 

Binary 

Get  current  XY 
and  buttons 
values 


After  return 


xyGetlnput  xpos 

(returns)  “43”  ;  the  current  X  coordinate  is  43 
xyGetlnput  xposypos,  buttons 

(returns)  “43,110,1”  ;  XY  coordinates  are  43,110  and  button  1  is  closed 


xyGetlnput  device=2,xpos,ypos 

(returns)  “128,145”  ;  device  2  XY  coordinates  are  128, 145 


AX 

4100 

;  xyGetlnput  decimal  ID 

BX 

3 

;  number  of  parameters 

ES:DI[0] 

61 

;  xpos  decimal  ID 

ES:DI[4] 

any  value 

;  place  holder  for  xpos  value  after  return 

ES:DI[8] 

67 

;  ypos  decimal  ID 

ES:DI[C] 

any  value 

;  place  holder  for  ypos  value  after  return 

ES:DI[10] 

5 

;  buttons  decimal  ID 

ES:DI[14] 

any  value 

;  place  holder  for  button  bit  field  after  return 

AX 

0 

;  returns  0  if  successful  (nonzero  if  not) 

ES:DI[4] 

X  position 

;  X  position 

ES:DI[C] 

Y  position 

;  Y  position 

ES:DI[14] 

bit  field 

;  button  status  bit  field 
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xyGetState  Last  revision:  R  1 .0 

Type:  core 

Parameters 

ASCII  _ _ _ _ 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

cursor 

Extended 

None 

N/A 

1  (on)  1 0  (off) 

Integer 

No  action 

defdevice 

Core 

None 

N/A 

Default  input 
device,  0-15 

Integer 

No  action 

device 

Core 

Logical  input 
device,  0-15 

Integer 

None 

N/A 

Default 

device 

tbuttons 

Core 

None 

N/A 

Total  available  for 
device 

Integer 

No  action 

tdevices 

Core 

None 

N/A 

Total  installed  for, 
0-15 

Integer 

No  action 

xmax 

Core 

None 

N/A 

Maximum  possible 
X  value 

Integer 

No  action 

xmaxclip 

Core 

None 

N/A 

Current  maximum 

X  value 

Integer 

No  action 

xmln 

Core 

None 

N/A 

Minimum  possible 

X  value 

Integer 

No  action 

xmincllp 

Core 

None 

N/A 

Current  minimum 

X  value 

Integer 

No  action 

ymax 

Core 

None 

N/A 

Maximum  possible 
Y  value 

Integer 

No  action 

ymaxclip 

Core 

None 

N/A 

Current  maximum 

Y  value 

Integer 

No  action 

ymin 

Core 

None 

N/A 

Minimum  possible 

Y  value 

Integer 

No  action 

yminclip 

Core 

None 

N/A 

Current  minimum 

Y  value 

Integer 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  is  specified,  at  least 
one  other  parameter  must  be  specified. 
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xyGetState 

Binary 

Command  code:  4102  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

cursor 

Extended 

11 

Integer 

Any  value 

1  (on)  j  0  (off) 

No  action 

defdevice 

Core 

12 

Integer 

Any  value 

Default  input 
device,  0-15 

No  action 

device 

Core 

14 

Integer 

Logical  input 
device,  0-15 

None 

Default 

device 

tbuttons 

Core 

44 

Integer 

Any  value 

Total  available  for 
device 

No  action 

jtdevices 

Core 

45 

Integer 

Any  value 

Total  installed  for, 
0-15 

No  action 

xmax 

Core 

56 

Integer 

Any  value 

Maximum  possible 
X  value 

No  action 

xmaxclip 

Core 

57 

Integer 

Any  value 

Current  maximum 

X  value 

No  action 

xmln 

Core 

58 

Integer 

Any  value 

Minimum  possible 

X  value 

No  action 

xminclip 

Core 

59 

Integer 

Any  value 

Current  minimum 

X  value 

No  action 

ymax 

Core 

62 

Integer 

Any  value 

Maximum  possible 
Y  value 

No  action 

ymaxclip 

Core 

63 

Integer 

Any  value 

Current  maximum 

Y  value 

No  action 

ymin 

Core 

64 

Integer 

Any  value 

Minimum  possible 

Y  value 

No  action 

ymlnclip 

Core 

65 

Integer 

Any  value 

Current  minimum 

Y  value 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  is  specified,  at  least 
one  other  parameter  must  be  specified. 


Description 

Summary  xyGetState  returns  information  about  the  current  values  of  the  coordinate 

space,  and  available  devices  and  capabilities.  VDI  Management  maintains  a 
copy  of  device-specific  parameters  including  coordinates  for  each  logical 
device. 
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xyGetState 

Cursor  parameter  The  cursor  parameter  returns  one  if  the  graphics  cursor  is  visible.  Cursor 
returns  zero  if  the  input  device  supports  a  cursor  that  is  not  visible  or  the  de¬ 
vice  does  not  support  a  cursor,  in  which  case,  the  cursor  must  always  be  off. 


Cursor  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter).  _ 


Def  device  The  defdevice  parameter  returns  the  logical  number  of  the  default  XY-input 

parameter  device  as  by  xySet  defdevice.  VDI  management  directs  all  XY  commands  to 

this  device  unless  a  command  includes  a  device  parameter  (see  below)  direct¬ 
ing  it  to  a  different  input  device. 


Device  parameter  The  device  parameter  directs  xyGetState  to  the  specified  logical  device 

number  regardless  of  the  default  device  number  as  set  by  xySet  defdevice. 
Because,  in  general,  device  affects  the  command  with  which  it  is  associated 
only,  the  parameter  does  not  affect  the  return  value  for  defdevice  (see 
above)  when  the  two  parameters  are  used  together. 


Specifying  device  with  no  other  parameter  returns  error  49  (Insufficient  pa¬ 
rameters).  Specifying  a  nonexistent  or  uninstalled  device  returns  error  160 
(Invalid  device  number).  Specifying  an  uninitialized  device  causes  error  81 
(Device  not  initialized). 


Tbuttons  The  tbuttons  parameter  returns  the  total  number  of  buttons  available  for 

parameter  the  default  or  specified  XY-input  device. 


Tdevices  The  tdevices  parameter  returns  the  total  number  of  logical  XY-input  devices 

parameter  for  which  VDI  Management  was  configured  at  installation.  If  only  one  device 

is  installed,  it  is  numbered  zero  and  tdevices  returns  one.  This  parameter 
alerts  the  application  to  systems  that  have  more  than  one  available  input  de¬ 
vice,  for  example  a  mouse  and  touch  screen. 


Xmln,  ymln,  The  xmin,  ymin,  xmax,  ymax  parameters  return  the  current  scaling  of  the 

xmax,  and  ymax  XY-coordinate  system.  Hie  xmin  and  ymin  values  are  the  coordinates  corre- 
parameters  sponding  to  the  physical  location  of  the  upper  left  comer  of  the  active  graph¬ 

ics  area.  The  xmax  and  ymax  values  correspond  to  the  lower  right  corner  of 
the  active  graphics  area.  VDI  Management  scales  absolute  positioning  infor¬ 
mation  to  the  space  defined  by  these  parameters. 
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xyGetState 

Xmlnclip, 
yminclip, 
xmaxcllp,  and 
ymaxcllp 
parameters 

Parameters 
resulting  In  errors 


Notes 


Returns 

ASCII 


Binary 


See  also: 


Examples 

ASCII 

Get  total  devices, 
and  default  device 

Get  current 

XY-coordinate 

space 

Get  available 
buttons  for 
device  2 


The  xminclip,  yminclip,  zmazclip,  and  ymaxclip  parameters  return  the 
area  within  the  XY-coordinate  space  within  which  changes  of  position  are 
reported. 


If  a  parameter  causes  an  error,  xyGetState  returns  immediately  with  the 
error  message.  The  command  does  not  return  partial  responses  for  other  pa¬ 
rameters  that  did  not  cause  errors. 


1.  Trying  to  queue  xyGetState  causes  error  177  (Command  cannot  be 
queued)  at  the  time  of  the  attempt. 


On  success:  Comma-separated  list  of  values  for  requested  parameters  as 
described  above. 

On  failure:  “ERROR  n. . 

On  success:  AX  =  0.  Values  associated  with  requested  parameters  are  32-bit 
values  of  the  types  given  in  the  binary  parameter  table  above. 

On  failure:  AX  =  error  number.  Any  return  values  in  the  parameter  block  ad¬ 
dressed  by  ES:DI  are  undefined  and  should  be  ignored. 


syGetState,  vdGetState,  vmGetState,  xyGetlnput,  xylnit,  xySet. 


xyGetState  tdevices,defdevice 

(returns)  “2,1”  ;  two  devices,  number  1  is  selected 

xyGetState  xmin,ymin,xmax,ymax 

(returns)  “0,0,639,199”  ;  x  values  will  be  between  0  and  639, 

;  and  y  values  between  0  and  199 

xyGetState  tbuttons,device=2 

(returns)  “3”  ;  three  buttons  available 
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xyGetState 


Binary 


Determine  If 

AX 

4102 

cursor  is  on 

BX 

1 

ES:DI[0] 

11 

ES:DI[4] 

any  value 

After  return 

AX 

0 

ES:DI[4] 

1 

;  xyGetState  decimal  ID 
;  number  of  parameters 
;  cursor  decimal  ID 

;  place  holder  for  cursor  value  sifter  return 

;  returns  0  if  successful  (nonzero  if  not) 

;  graphics  cursor  is  on  (0  =  off) 
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xylnit 


Last  revision:  R  1.0 
Type:  core 


Parameters 

ASCII 


Parameter 

Core  or 

Associated  calling 

Type 

Associated  return 

Type 

Default  if 

extended 

value 

as 

ASCII 

value 

as 

ASCII 

parameter 
not  used 

device 

Core 

Logical  input 
device,  0-15 

Integer 

None 

N/A 

Default 

device 

This  command  can  be  issued  with  no  parameters. 


Binary 

Command  code:  4103  decimal. 


A  Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

device 

Core 

14 

Integer 

Logical  input 
device,  0-15 

None 

Default 

device 

(This  command  can  be  issued  wit 

h  no  parameters. 

Description 


Summary  xylnit  initializes  XY-input  hardware  and  the  xy  service  group,  placing  both 

in  a  known  state,  xylnit  must  be  issued  for  each  attached  XY-input  device 
that  will  be  used  by  the  application. 


Device  parameter  The  device  parameter  specifies  the  logical  number  of  the  XY-input  device  to 
be  initialized.  If  device  is  omitted,  xylnit  initializes  the  default  device  as  set 
by  xySet  defdevice.  If  xySet  has  not  been  used  to  set  a  default  input  device, 
the  default  device  is  defined  to  be  number  zero,  xylnit  does  not  change  the 
default  input  device  if  a  device  other  than  the  default  is  specified.  To  change 
the  default,  use  xySet  defdevice. 


Specifying  a  nonexistent  or  uninstalled  device  returns  error  160  (Invalid  de¬ 
vice  number). 
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xylnit 

Conditions  set  by  xylnit  sets  the  parameters  in  the  following  table  to  the  specified  values. 

xylnit 


j  Parameter  values  set  by  xylnit  j 

Parameter 

Value 

Command  reference 

tbuttons 

Total  available  for  device 
being  initialized 

none 

tdevices 

Total  installed,  0-15 

none 

xmax 

639 

xySet 

xmaxclip 

639 

xySet 

xmln 

0 

xySet 

xmincllp 

0 

xySet 

xpos 

0 

xySet 

ymax 

199 

xySet 

ymaxclip 

199 

xySet 

ymln 

0 

xySet 

yminclip 

0 

xySet 

ypos 

0 

xySet 

Notes  1.  xyGetState  tdevices  returns  the  total  number  of  XY-input  devices  for 

which  VDI  Management  was  installed.  This  command  can  be  used  after 
the  first  xylnit  to  determine  the  number  of  additional  devices  to  initialize. 

2.  Trying  to  queue  xylnit  causes  error  177  (Command  cannot  be  queued)  at 
the  time  of  the  attempt. 


Returns 


ASCII 

On  success:  “OK”. 

On  failure:  “ERROR  n..”. 

Binary 

On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 

See  also:  sylnit,  vdlnit,  vmlnit,  xyGetState,  xySet. 
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xylnit 


Examples 


ASCII 


Initialize  device  0 
and  xy  service 
group 

Initialize  device  1 


xylnit 

(returns)  “OK" 

xylnit  devices  1 
(returns)  “OK" 


;  first  time  command  is  issued 


;  device  1  successfully  initialized 


Binary 


Initialize  device  0 

AX 

4103 

and  xy  service 

BX 

0 

group 

After  return 

AX 

0 

;  xylnit  decimal  ID 
;  number  of  parameters 

;  returns  0  if  successful  (nonzero  if  not) 
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xySet  Last  revision:  R  1.0 

Type:  core 

Parameters 

ASCII  _ 


Parameter 

Core  or 
extended 

Associated  calling 
value 

Type 

as 

ASCII 

Associated  return 
value 

Type 

as 

ASCII 

Default  if 
parameter 
not  used 

cursor 

Extended 

1  (on)  1 0  (off) 

Integer 

None 

N/A 

No  action 

defdevice 

Core 

Logical  input 
device,  0-15 

Integer 

None 

N/A 

No  action 

device 

Core 

Logical  input 
device,  0-15 

Integer 

None 

N/A 

Default 

device 

xmax 

Core 

Maximum  possible 
X  value 

Integer 

None 

N/A 

No  action 

xmaxclip 

Core 

Current  maximum 

X  value 

Integer 

None 

N/A 

No  action 

xmin 

Core 

Minimum  possible 

X  value 

Integer 

None 

N/A 

No  action 

xminclip 

Core 

Current  minimum 

X  value 

Integer 

None 

N/A 

No  action 

xpos 

Core 

X  position 

Integer 

None 

N/A 

No  action 

ymax 

Core 

Maximum  possible 
Y  value 

Integer 

None 

N/A 

No  action 

ymaxclip 

Core 

Current  maximum 

Y  value 

Integer 

None 

N/A 

No  action 

ymin 

Core 

Minimum  possible 

Y  value 

Integer 

None 

N/A 

No  action 

ymlnclip 

Core 

Current  minimum 

Y  value 

Integer 

None 

N/A 

No  action 

ypos 

Core 

Y  position 

Integer 

None 

N/A 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned.  It  device  is  specified,  at  least 
one  other  parameter  must  be  specified.  _  _ 
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xySet 

Binary 

Command  code:  4109  decimal. 


Parameter 

Core  or 
extended 

Token 

number 

(decimal) 

Type 

Associated  calling 
value 

Associated  return 
value 

Default  if 
parameter 
not  used 

cursor 

Extended 

11 

Integer 

1  (on)  1 0  (off) 

None 

No  action 

defdevlce 

Core 

12 

Integer 

Logical  input 
device,  0-15 

None 

No  action 

device 

Core 

14 

Integer 

Logical  input 
device,  0-15 

None 

Default 

device 

xmax 

Core 

56 

Integer 

Maximum  possible 
X  value 

None 

No  action 

xmaxclip 

Core 

57 

Integer 

Current  maximum 

X  value 

None 

No  action 

xmin 

Core 

58 

Integer 

Minimum  possible 

X  value 

None 

No  action 

xminclip 

Core 

59 

Integer 

Current  minimum 

X  value 

None 

No  action 

xpos 

Core 

61 

Integer 

X  position 

None 

No  action 

ymax 

Core 

62 

Integer 

Maximum  possible 
Y  value 

None 

No  action 

ymaxcllp 

Core 

63 

Integer 

Current  maximum 

Y  value 

None 

No  action 

ymin 

Core 

64 

Integer 

Minimum  possible 

Y  value 

None 

No  action 

yminclip 

Core 

65 

Integer 

Current  minimum 

Y  value 

None 

No  action 

ypos 

Core 

67 

Integer 

Y  position 

None 

No  action 

At  least  one  parameter  is  required  or  an  error  is  returned.  If  device  is  specified,  at  least 
one  other  parameter  must  be  specified. _ 


Description 

Summary  xySet  defines  the  XY-coordinate  space,  sets  the  default  input  device,  turns 

the  cursor  on  and  off,  and  sets  the  current  XY  coordinates.  Each  parameter 
stays  in  effect  for  either  the  current  or  specified  device  regardless  of  the 
graphics  mode  until  reset  with  xySet  or  xylnit. 
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Cursor  parameter 


Defdevice 

parameter 


Device  parameter 


Xmln,  ymln, 
xmax,  and  ymax 
parameters 


Xmlnclip, 
ymlnclip, 
xmaxclip,  and 
ymaxclip 
parameters 


Xpos  and  ypos 
parameters 


xySet 

The  cursor  parameter  enables  and  disables  a  graphics  cursor  if  one  is  avail¬ 
able.  For  example,  if  the  device  is  a  mouse,  xySet  cursors  1  enables  the  cur¬ 
sor  and  makes  it  visible.  Updating  the  position  of  such  a  cursor  is  a 
background  function.  If  the  input  device  does  not  support  a  cursor,  turning 
the  cursor  on  returns  error  87  (Action  not  supported  by  device). 


Cursor  is  an  extended  parameter.  Using  an  unimplemented  extended  parameter 
causes  error  48  (Unknown  parameter). 


The  defdevice  parameter  specifies  the  default  input  device  to  be  used  when 
more  than  one  input  device  is  available.  Specifying  a  nonexistent  or  unin¬ 
stalled  device  returns  error  160  (Invalid  device  number).  Specifying  an  unini¬ 
tialized  device  causes  error  81  (Device  not  initialized). 


The  device  parameter  directs  xySet  to  the  specified  logical  device  number 
regardless  of  the  default  input  device  as  set  by  xySet  defdevice  (see  above). 


Specifyingdevice  with  no  other  parameter  returns  error  49  (Insufficient  pa¬ 
rameters).  Specifying  a  nonexistent  or  uninstalled  device  returns  error  160 
(Invalid  device  number).  Specifying  an  uninitialized  device  causes  error  81 
(Device  not  initialized). 


The  xmin,  ymin,  xmax,  and  ymax  parameters  set  the  scaling  of  the  XY-co- 
ordinate  space  to  the  physical  screen.  The  values  correspond  to  the  upper  left 
and  lower  right  comers  of  the  active  graphics  display  area.  Legal  Values 
range  -32768-32767.  Regardless  of  the  values,  xmin  and  xmax  always  map 
to  the  left  and  right  edges  of  the  screen,  respectively;  ymin  and  ymax  always 
map  to  the  top  and  bottom  edges. 


The  xminclip,  yminclip,  xmaxclip,  and  ymaxclip  parameters  define  a  con¬ 
strained  area  within  the  coordinate  space  for  reporting  coordinate  movement. 
Coordinates  values  are  returned  only  within  the  defined  clip  area.  The  clip¬ 
ping  area  is  initially  defined  to  be  the  same  as  xmin,  ymin,  xmax,  and 
ymax.  Specifying  a  clipping  value  outside  the  scaling  of  the  XY-coordinate 
system  (see  above)  returns  error  51  (Parameter  value  invalid  or  out  of  range). 


The  xpos  and  ypos  parameters  set  the  XY  coordinates  to  a  specific  location. 
These  parameters  are  especially  useful  for  initially  positioning  the  XY-input 
device.  An  xpos  or  ypos  value  outside  the  clipping  values  (see  above)  sets 
the  coordinate  to  the  limit  of  the  respective  clipping  range. 
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xySet 


Notes  1.  xyGetState  tdevices  returns  the  number  of  input  devices  that  can  be  se- 

.  lected  by  xySet  defdevice,  assuming  all  devices  for  which  VDI  Manage¬ 
ment  was  installed  are  available. 


Returns 

ASCII  On  success:  “OK”. 

On  failure:  “ERROR  n...” 

Binary  On  success:  AX  =  0. 

On  failure:  AX  =  error  number. 


See  also:  xyGetlnput,  xyGetState,  xylnit. 


Examples 

ASCII 

Set  XY  position  xySet  xpos=40,ypos=50 

(returns)  “OK”  ;  XY  position  is  40,50 

Turn  device  2  xySet  device=2, cursors  1 

cursor  on  (returns)  “OK” 

Match  coordinate  xySet  xmin=0,ymin=0,xmax=639 ,ymax=479 

space  to  VGA  max  (returns)  “OK" 

Set  maximum  xySet  xmaxclip=200,ymaxclip=200 

Clipping  values  (returns)  “OK”  ;  report  change  if  X  or  Y  is  less  than  200 

Binary  examples 

Turn  on  XY  cursor  AX  4109  ;  xySet  decimal  ID 

BX  1  ;  number  of  parameters 

ES:DI[0]  11  ;  cursor  decimal  ID 

ES:DI[4]  1  ;  turn  cursor  on 

After  return  AX  0  ;  returns  0  if  successful  (nonzero  if  not) 


9-18 


Release  R  1.0 


April  15, 1990 


A  Default  positions  of 
graphics  relative  to  video 


This  appendix  explains  how  to  determine  the  size  and  position  of  graphics 
relative  to  background  video.  To  ensure  the  compatibility  of  hardware,  VDI 
Management  software,  and  applications,  the  active  graphics  screen  for  a 
given  application  should  always  have  the  same  position  relative  to  the  active 
video  and  be  of  the  same  size.  However,  the  proper  position  of  graphics  can 
vary  with  the  video  standard  (NTSC  versus  PAL),  the  graphics  mode,  and  the 
adapter  type  (VGA  versus  CGA  and  EGA). 


Although  exact  registration  and  graphics  screen  sizes — within  one  or  two  pix¬ 
els  or  lines — may  require  user  calibration  using  a  position  reference  frame, 
proper  registration  can  be  calculated  with  reasonable  accuracy.  The  following 
sections  explain  how  to  determine  horizontal  and  vertical  graphics  positions 
for  both  NTSC  and  PAL  video. 


Because  no  absolute  specification  exists  for  the  size  and  position  of  the  back¬ 
ground  video  and  because  the  position  can  vary  in  post-production  generation  of 
videodiscs,  the  recommended  positions  in  this  appendix  are  guidelines  for  a 
nominal  video  image.  If  exact  positioning  is  critical,  the  videodisc  for  the  application 
should  include  a  reference  frame  for  user  calibration  at  run  time.  This  requires  VDI 
Management  implementations  to  support  dynamic  repositioning  of  graphics. 

Proper  registration  requires  accurately  setting  the  graphics  width  as  well  as  the 
origin.  Correctly  setting  the  origin  but  using  the  wrong  width  results  in  improper 
registration  on  the  right  side  of  the  video.  Generating  the  graphics  clock  so  that 
exactly  912  clock  cycles  equal  1  horizontal  period  assures  proper  width.  If  an 
overlay  method  does  not  guarantee  this  relationship,  implemented  must  provide 
a  way  to  adjust  the  graphics  width  and  the  reference  frame  must  provide  both  left 
and  right  registration  information. 
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A.1  Terms  of  reference 


Figure  A-l  shows  a  simplified  display  screen  including  video,  graphics,  sync 
signals,  and  blanking  intervals.  For  simplicity,  the  figure  shows  separate  hor¬ 
izontal  and  vertical  sync  signals.  Although  these  signals  may  be  thought  of  as 
separate  for  determining  graphics  positions,  they  may  be  combined  into  a 
composite  signal  in  actual  monitors. 


Figure  A-l. 
A  simplified 
diagram  of  an 
overlayed  display 
using  CGA  or  EGA 
graphics 


T 


Vertical  sync 


Vertical 

blanking 


Active  video 


~bi 


Horn. 

ilankingj 


Active 

video 


The  remaining  sections  of  this  appendix  use  the  following  terms: 

1.  Active  graphics:  The  portion  of  the  screen  where  graphics  can  appear. 

2.  Active  video:  The  portion  of  the  screen  where  video  can  appear.  This  is 
the  portion  of  horizontal  and  vertical  video  not  blanked  by  horizontal 
and  vertical  blanking. 

3.  Borden  The  portion  of  active  video  not  covered  by  active  graphics. 

4.  Horizontal  blanking:  The  time  period  during  which  the  display  is  blank 
for  horizontal  retracement. 
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5.  Horizontal  sync:  The  pulse  used  to  synchronize  the  horizontal  scan  of 
the  video  monitor. 

6.  Vertical  blanking:  The  time  period  during  which  the  display  is  blank  for 
vertical  retracement. 

7.  Vertical  sync:  The  pulse  used  to  synchronize  the  vertical  scan  of  the 
video  monitor. 

The  values  used  in  the  figures  and  calculations  for  horizontal  and  vertical 
positioning  are  based  on  accepted  definitions  for  NTSC  and  PAL  video.  The 
corresponding  standards  are  EIA  RS-170A  and  CCIR  470—1,  respectively. 

A.2  Special  considerations  for  VGA  graphics 


VGA  graphics  require  special  consideration  for  two  reasons.  The  first  deals 
with  the  differences  in  background  video  signals  and  vertical  timing.  The  sec¬ 
ond  deals  with  differences  in  active  graphics  sizes  for  the  same  video  modes 
when  considering  VGA  graphics  versus  CGA  and  EGA  graphics. 

A.2.1  Differences  in  signals  and  timing _ _ 

CGA  and  EGA  graphics  overlay  systems  typically  use  standard  15-kHz  back¬ 
ground  video.  For  these  systems,  accepted  video  standards  dictate  blanking 
interval  widths  and  the  starts  of  horizontal  and  vertical  sync.  Therefore,  CGA 
and  EGA  systems  can  use  the  starts  of  horizontal  and  vertical  sync  as  abso¬ 
lute  references  for  graphics  positioning  and  rely  on  constant  horizontal  signal 
widths  and  vertical  timing  for  a  given  video  standard,  either  NTSC  or  PAL. 

However,  VGA  systems  typically  use  scan-altered,  non- 15-kHz  modes.  The 
background  video  for  VGA  may  not  include  horizontal  or  vertical  sync  and 
blanking  interval  widths  may  vary.  Therefore,  graphics  positioning  must  use 
the  nominal  start  of  active  video  as  a  reference  instead  of  the  start  of  sync 
and  positioning  must  be  relative  to  the  active  video  rather  than  the  total 
video  including  blanking. 

A.2.2  Differences  in  the  size  of  active  graphics 


By  increasing  pixel  width,  VGA  graphics  cover  the  entire  width  of  active 
video,  leaving  borders  at  the  top  and  bottom  of  active  graphics  only.  However, 
a  CGA  or  EGA  adapter  used  to  display  graphics  in  the  same  mode  leaves  a 
border  around  all  edges  of  the  active  graphics. 

For  example,  VGA  mode  6  (640  x  200)  graphics  cover  the  entire  width  of  the 
active  video,  while  mode  6  (640  x  200)  graphics  from  a  CGA  or  EGA  adapter 
leave  a  visible  video  border  around  all  edges  of  the  active  graphics.  Therefore, 
compliant  VDI  Management  implementations  for  VGA  overlay  systems  must 
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support  both  graphics  that  map  to  the  left  and  right  edges  of  active  video 
and,  for  those  modes  that  are  CGA/EGA-compatible,  emulations  of  true  CGA 
and  EGA  systems  that  leave  a  border  around  all  edges  of  active  graphics. 


A.3  Horizontal  positions 


This  section  explains  how  to  determine  the  start  and  end  of  active  graphics 
relative  to  a  horizontal  video  signal.  The  horizontal  position  of  graphics  rela¬ 
tive  to  video  can  be  expressed  as  a  proportion  of  the  horizontal  video  signal 
width,  which  is  abbreviated  H.  Using  proportions  simplifies  determining  posi¬ 
tions  for  scan-altered  systems. 

Because  horizontal  sync  is  the  timing  reference  from  which  all  horizontal 
components  are  measured  in  15-kHz  video,  true  CGA  and  EGA  graphics  use 
the  start  of  horizontal  sync  as  a  reference  and  positions  can  be  expressed  as 
proportions  of  total  H.  Because  VGA  video  and  graphics  may  not  include  a 
horizontal  sync  signal  and  the  width  of  the  blanking  intervals  may  vaiy,  VGA 
graphics  modes  that  emulate  CGA  and  EGA  modes  are  measured  from  the 
nominal  start  of  active  video  and  expressed  as  a  proportion  of  active  H. 

A.3.1  General  assumptions  _ _ 


The  following  general  assumptions  are  used  in  determining  the  horizontal 
positions  of  active  graphics  relative  to  NTSC  and  PAL  video. 

1.  The  optimal  position  for  active  graphics  is  centered  horizontally  in  the 
active  video. 

Basis:  Nominal  common  practice.  However,  variations  in  graphics  posi¬ 
tioning  due  to  monitor  centering  adjustments  cannot  be  accounted  for  in 
the  recommendations  in  this  appendix. 

2.  One  horizontal  line  of  graphics  is  912  pixels  in  length.  The  active  graphics 
consist  of  a  640-pixel  window. 

Basis:  Apple  II  and  IBM  CGA  standards  define  a  640-pixel  active  graph¬ 
ics  window  in  a  912-pixel  horizontal  line.  The  graphics  are  about  85%  of 
the  total  displayable  window  to  allow  for  monitor  overscan.This  has  be¬ 
come  a  de  facto  standard  that  is  also  used  by  EGA  graphics.  CGA-  and 
EGA-based  overlay  systems  generally  follow  this  standard. 

3.  Because  color  graphics  standards  are  based  on  a  line  length  of  912  pixels, 
1/912  H  or  approximately  0.0011  H  is  the  finest  positioning  resolution 
available 

Basis:  Original  IBM  CGA  implementation. 

3.  Graphics  with  320-pixel  active  areas  cover  exactly  the  same  horizontal 
area  as  graphics  with  640-pixel  active  areas.  Therefore,  starting  and 
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ending  positions  based  on  calculations  using  640  pixels  are  valid  for  320- 
pixel  graphics. 

Basis:  The  pixel  width  for  320-pixel  graphics  modes  is  exactly  twice  the 
width  for  640-pixel  graphics  and  the  number  of  pixels  for  320-pixel 
graphics  is  exactly  one  half  the  number  of  pixels  for  640-pixel  modes. 


A.3.2  NTSC 


Figure  A-2  shows  the  timing  for  one  line  of  15-kHz  NTSC  video  including  the 
position  of  CGA  and  EGA  640-  or  320-pixel  graphics.  The  timing  values  in 
the  figure  are  either  taken  directly  from  or  derived  from  the  accepted  stan¬ 
dard  for  NTSC  video.  The  calculations  in  this  section  are  based  on  the  values 
shown  in  the  figure. 


Figure  A-2. 
One  horizontal  line 
of  NTSC  video  with 
640 -  or  320-pixel 
overlayed  graphics 


10.9±0.2 


1-510.1 

f 


9.410.1  —I 


|-Sync-| 
I—  Blanking 


rp 

I  4.042 


52.65610.2 


Active  graphics 
(640-  nr  320-pixel  CGA/EGA) 


hies 


Active  video 


All  values  in  microseconds. 


I  ^ 
4.042 


Position  of  true  CGA  and  EGA  graphics _ 

To  determine  the  correct  position  of  true  CGA  and  EGA  graphics  over  video 
as  a  fraction  of  a  horizontal,  15.734-kHz,  NTSC,  video  signal  given  the  timing 
shown  in  Figure  A-2,  use  the  following  equations  and  assumptions  for  640- 
pixel  graphics.  Note  that  the  resulting  positions  hold  for  320-pixel  graphics. 


The  general  equation  for  the  starting  position  of  true  CGA  and  EGA  graphics 
centered  in  active  video  as  a  proportion  of  total  H  using  the  start  of  sync  as  a 
reference  can  be  expressed  as: 


(1)  GH start  = 


AV  tart  +  ^>aet*ve  —  ^ displayed )  X  P width 
2 

Htatal 
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Similarly,  the  general  equation  for  determining  the  ending  position  of  true 
CGA  and  EGA  graphics  as  a  proportion  of  total  H  can  be  expressed  as: 


AV start  + 


( P active  —  Pdisplayed)  X  P width 


(2)  GHend  — ' 


+  ( Pdisplayed  X  P width) 


H total 


Where,  GH  stands  for  “graphics  horizontal,”  and  for  NTSC  video  and  640- 
pixel  resolutions: 

1.  The  nominal  start  of  active  video  is: 

AV start  —  9.4  |1S 
from  Figure  A-2. 

2.  The  total  number  of  pixels  corresponding  to  the  width  of  active  video  is: 

Pactwe  =  X  912  pixels  -  756  pixels 

63.556  ps 

from  Figure  A-2  and  the  de  facto  standard  (see  assumption  2  in  Sec¬ 
tion  A.3.1). 

3.  The  total  number  of  displayed  pixels  is: 

Pdisplayed  -  640  pixels 

from  the  de  facto  standard  (see  assumption  2  in  Section  A.3.1). 

4.  The  total  width  of  the  video  signal  is 

H total  —  63.556  ps 

from  Figure  A-2. 

5.  The  width  of  one  pixel  is 

Pwidth  =  63ff06^  =  0.06969  ps 


Solving  equation  1  for  the  starting  position  of 640-pixel  graphics  yields: 

0  [  (756  -  640)  x  0.06969 

GHstart  = - g35gf - =  0.2115  Htotal 


Solving  equation  2  for  the  ending  position  of 640-pixel  graphics  yields: 


9.4  + 
GHend  — - 


(756  -  640) x  0.06969 
2 

63.556 


+  (640  x  0.06969) 


0.9133  Htotal 
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For  NTSC  video  these  values  equate  to  left  and  right  border  widths  of  4.042 
|is  and  a  start  of  active  graphics  at  approximately  13.4  ps  after  the  start  of 
horizontal  sync.  The  latter  value  can  be  reliably  verified  with  an  accurate 
oscilloscope. 


Position  of  VGA  graphics  emulating 

CGA  and  EGA  modes _ 

True  VGA  graphics  map  to  the  edges  of  active  video  and  require  no  calcula¬ 
tions.  However,  the  starting  and  ending  positions  of  VGA  graphics  emulating 
CGA  and  EGA  graphics  must  be  calculated.  To  determine  the  correct  position 
of  such  graphics  over  video  as  a  fraction  of  a  horizontal,  15.734-kHz,  NTSC, 
video  signal  given  the  timing  shown  in  Figure  A-2,  use  the  following  equa¬ 
tions  and  assumption  for  640-pixel  graphics.  Note  that  the  resulting  positions 
hold  for  320-pixel  graphics. 


The  general  equation  for  the  starting  position  of  VGA  emulating  CGA  and 
EGA  graphics  centered  in  active  video  as  a  proportion  of  active  H  using  the 
nominal  start  of  video  as  a  reference  can  be  expressed  as: 


(3) 


GH start  = 


( Pactive  —  P displayed )  X  P width 

_ 2 _ 

H active 


Similarly,  the  general  equation  for  determining  the  ending  position  of  VGA 
graphics  emulating  CGA  and  EGA  graphics  as  a  proportion  of  active  H  can  be 
expressed  as: 


(4) 


+  {PiivUjtd  xpwidih) 

GHend  = - n - 

it  active 


These  equations  are  identical  to  equations  1  and  2  in  the  previous  section 
except  that  AV$tart  is  now  equal  to  zero  and  therefore  dropped  from  the  equa¬ 
tions  and  that  Htotal  has  been  changed  to  Haetive  where: 

Hactive  —  52.656  ps 
from  Figure  A-2. 


Solving  equation  3  for  the  starting  position  of 640-pixel  graphics  yields: 
(756  -  640) x  0.06969 

GH  start  — - 52  656 - =  0.0768  Hactive 


April  15, 1990 


Release  R  1.0 


A-7 


Recommended  Practices  for  Interactive  Video  Portability 


Solving  equation  4  for  the  ending  position  of  640-pixel  graphics  yields: 
(756- 640)  x  0.06969  +  (64Q  x  0  06969) 

GHend  = - cVTcec - =  0.924  Hactive 


A.3.3  PAL 


Figure  A-3  shows  the  timing  for  one  line  of  15-kHz  PAL  video  including  the 
position  of  CGA  and  EGA  640-  and  320-pixel  graphics.  The  timing  values  in 
the  figure  are  either  taken  directly  firom  or  derived  from  the  accepted  stan¬ 
dard  for  PAL  video.  The  calculations  in  this  section  are  based  on  the  values 
shown  in  the  figure. 


Figure  A-3. 
One  horizontal  line 
of  PAL  video  with 
640-  and  320-pixel 
overlayed  graphics 
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The  general  equations  used  to  calculate  graphics  positions  for  PAL  are  identi¬ 
cal  to  those  for  NTSC.  However,  the  values  used  for  the  equation  variables 
differ  because  of  differences  in  horizontal  timing.  For  convenience,  all  equa¬ 
tions  and  variable  values  are  repeated  in  the  following  sections. 


Position  of  true  CGA  and  EGA  graphics 


To  determine  the  correct  position  of  true  CGA  and  EGA  graphics  over  video 
as  a  fraction  of  a  horizontal,  15.625-kHz,  PAL,  video  signal  given  the  timing 
shown  in  Figure  A-3,  use  the  following  equations  and  assumptions  for  640- 
pixel  graphics.  Note  that  the  resulting  positions  hold  for  320-pixel  graphics. 
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The  general  equation  for  the  starting  position  of  true  CGA  and  EGA  graphics 
centered  in  active  video  as  a  proportion  of  total  H  using  the  start  of  horizon¬ 
tal  sync  as  a  reference  can  be  expressed  as: 


(5)  GH start  — 


...  ( P active  ~  P displayed)  x  P width 

AVstart  + - ^ - 

H total 


Similarly,  the  general  equation  for  determining  the  ending  position  of  true 
CGA  and  EGA  graphics  as  a  proportion  total  H  width  can  be  expressed  as: 


AY  start  + 


( P active  ~  Pdisplayed)  *  P width 


(6)  GHend  —  ' 


+  ( Pdisplayed  x  P width) 


H total 


Where,  for  PAL  video  and  640-pixel  resolutions: 

1.  The  nominal  start  of  active  video  is: 

AVstart  =  10.5  ps 
from  Figure  A— 3. 

2.  The  total  number  of  pixels  corresponding  to  the  width  of  active  video  is: 

Pactive  =  *  912 pixels  -  740 pixels 

04.U  (IS 

from  Figure  A-3  and  the  de  facto  standard  (see  assumption  2  in  Sec¬ 
tion  A.3.1). 

3.  The  total  number  of  displayed  pixels  is: 

Pdisplayed  =  640  pixels 

from  the  de  facto  standard  (see  assumption  2  in  Section  A.3.1). 

4.  The  total  width  of  the  video  signal  is 

Htotal  =  64.0  (IS 

from  Figure  A-3. 

5.  The  width  of  one  pixel  is 

=  =  0.07018  ms 


Solving  equation  5  for  the  starting  position  of  640-pixel  graphics  yields: 

1Q  5  (  (740  -  640)  x  0.07018 
GH  start  - 640 - -  Htotal 
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Solving  equation  6  for  the  ending  position  of  640-pixel  graphics  yields: 

10.5  +  (74°  ~  a°?— 8  +  (640  x  0.07018) 

GHend  = - - - gj-Q - -  0.9207  H total 

For  PAL  video  these  values  equate  to  left  and  right  border  widths  of  3.509  ps 
and  a  start  of  active  graphics  at  approximately  14.0  ps  after  the  start  of  hori¬ 
zontal  sync.  The  latter  value  can  be  reliably  verified  with  an  accurate 
oscilloscope. 


Position  of  VGA  graphics  emulating 

CGA  and  EGA  modes _ 

True  VGA  graphics  map  to  the  edges  of  active  video  and  require  no  calcula¬ 
tions.  However,  the  starting  and  ending  positions  of  VGA  graphics  emulating 
CGA  and  EGA  graphics  must  be  calculated.  To  determine  the  correct  position 
of  such  graphics  over  video  as  a  fraction  of  a  horizontal,  15.625-kHz,  PAL, 
video  signal  given  the  timing  shown  in  Figure  A-3,  use  the  following  equa¬ 
tions  and  assumptions  for  640-pixel  graphics.  Note  that  the  resulting  posi¬ 
tions  hold  for  320-pixel  graphics. 


The  general  equation  for  the  starting  position  of  VGA  emulating  CGA  and 
EGA  graphics  centered  in  active  video  as  a  proportion  of  active  H  using  the 
nominal  start  of  video  as  a  reference  can  be  expressed  as: 


(P active  ~  P displayed)  X  P width 


(7)  GHstart  —  ' 


H active 


Similarly,  the  general  equation  for  determining  the  ending  position  of  VGA 
graphics  emulating  CGA  and  EGA  graphics  as  a  proportion  of  active  video 
can  be  expressed  as: 


(8) 


GHend  = 


+  {Pduplaytd  x  pM) 

Hactive 


These  equations  are  identical  to  equations  5  and  6  in  the  previous  section  ex¬ 
cept  that  AV start  is  now  equal  to  zero  and  therefore  dropped  from  the  equa¬ 
tions  and  that  Htotal  has  been  changed  to  Hactive  where: 

Hactive  ~  51.95  )i£ 


from  Figure  A-3. 


A-10 


Release  R  1.0 


April  15, 1990 


Appendix  A.  Default  positions  of 
_ graphics  relative  to  video 


Solving  equation  7  for  the  starting  position  of  640-pixel  graphics  yields: 
(740  -  640) x  0.07018 

GHstart  — - gg - —  0.0675  Hactiue 

Solving  equation  8  for  the  ending  position  of  640-pixel  graphics  yields: 

(740-  640)  x  0.07018  +  (64Q  x  0  07018) 

GHend  = - - g  gg - -  0.9321  H active 


A.4  Vertical  positions 


This  section  explains  how  to  determine  the  start  and  end  of  active  graphics 
relative  to  vertical  video  timing.  The  vertical  position  of  graphics  can  be  ex¬ 
pressed  both  in  lines  and  as  a  proportion  of  vertical  timing,  which  is  abbre¬ 
viated  V.  Using  proportions  simplifies  determining  positions  for  scan-altered 
systems. 


A.4.1  General  assumptions 


The  following  general  assumptions  are  used  in  determining  the  vertical  posi¬ 
tions  of  active  graphics  relative  to  NTSC  and  PAL  video. 

1.  The  optimal  position  for  active  graphics  is  centered  vertically  in  the  active 
video. 

Basis:  Nominal  common  practice.  However,  note  that  variations  in 
graphics  positioning  due  to  monitor  centering  adjustments  cannot  be 
accounted  for  in  the  recommendations  in  this  appendix. 

2.  Vertical  resolution  is  expressed  relative  to  fields,  not  frames.  VGA  480-line 
mode  converts  to  240  lines  for  single-field  for  computations. 

Basis:  Observation. 


A.4.2  NTSC 


Figure  A-4  shows  the  timing  for  15-kHz  NTSC  video  including  the  position  of 
200-line  graphics.  The  timing  values  in  the  figure  are  either  taken  directly 
from  or  derived  from  the  accepted  standard  for  NTSC  video.  The  calculations 
in  this  section  are  based  on  the  values  shown  in  the  figure. 
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Figure  A-4. 
NTSC  vertical 
timing  with  200-line 
overlay ed  graphics 


b  20-21- 
3 

/ 

*■17-18 


Li 

I'M 

Sync 


* 

20 


Blanking 

All  values  in  lines. 


262.5 


■241.5-242.5 


_  Active  graphics 
(200  lines) 


* 

21 


Active  video 


Position  of  graphics  in  lines  relative  to  vertical  sync 

To  determine  the  correct  position  of  graphics  over  video  as  the  number  of 
lines  relative  to  the  start  of  vertical  sync  for  a  15.734-kHz,  NTSC,  video  sig¬ 
nal  given  the  timing  shown  in  Figure  A-4,  use  the  following  equations  and 
assumptions.  Note  that  the  calculations  can  easily  be  modified  for  different 
numbers  of  lines. 

Note:  The  NTSC  standard  specifies  a  vertical  blanking  interval  of  21  lines 
with  error  limits  of  +0  and  -1  lines  and  a  total  vertical  field  of  262.5  lines. 

The  calculations  below  assume  a  blanking  interval  of  21  lines,  an  active  video 
height  of  241.5  lines,  and  a  nominal  start  of  active  video  at  18  lines  from  the 
start  of  vertical  sync. 

The  general  equation  for  the  starting  position  of  graphics  centered  in  active 
video  as  the  number  of  lines  relative  to  the  start  of  vertical  sync  can  be 
expressed  as: 

(9)  GV»Wrt  =  AW  - 

Similarly,  the  general  equation  for  the  ending  position  of  graphics  as  the 
number  of  lines  relative  to  the  start  of  vertical  sync  can  be  expressed  as: 

(10)  GVtnd  ‘AVm*  .-.Ssig*  4 

Where  GV  stands  for  “graphics  vertical,”  and  for  NTSC  video: 

1.  The  nominal  start  of  active  video  is: 

AV start  =  18  lines 

from  Figure  A-4. 
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2.  The  number  of  active  video  lines  is: 

V active  =  24  X. 5  lines 
from  Figure  A— 4. 

3.  The  number  of  active  graphics  lines  is  either: 

Gactive  =  200  lines 

for  640  x  200  and  320  x  200  graphics,  or: 

Gactive  =  240  lines 

for  640  x  480  graphics  (see  assumption  2  in  Section  A.4.1.) 

Starting  and  ending  positions  for  200-line  graphics 

Solving  equation  9  for  the  start  of  200-line  graphics  yields: 

GVstart  =  18  + - - - “  39  lines 

Solving  equation  10  for  the  end  of 200-line  graphics  yields 
GVend  =  18  +  — -1-52~-2—  +  200  *  239  lines 

Starting  and  ending  positions  for  240-line  (640  x  480)  graphics 

Solving  equation  9  for  the  start  of 240-line  graphics  yields: 

GVstart  =  18  + - - - =  18.75  lines 

Solving  equation  10  for  the  end  of 240-line  graphics  yields 

GVend  =  18  +  ~~5~  2—  +  240  =  258.75  lines 

Given  the  derived  values  above,  VGA  240-line  modes  actually  leave  borders 
of  1  line  and  0.5  lines.  To  avoid  screen  disturbance,  hardware  implemented 
may  want  to  blank  these  borders.  Although  this  is  not  a  compliance  require¬ 
ment,  it  is  recommended. 

Position  of  graphics  as  a  proportion  of  total  video. 

To  calculate  the  position  of  graphics  as  a  proportion  of  total  vertical  timing, 
simply  change  equations  9  and  10  to  yield: 

AVstart  +  i— ****  ~  Gactive^ 

(11)  GVstart  - - 77 - - - 
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...  ,  (V active  —  Gactive)  ,  n 

A  V start  + - x - *"  G active 


(12)  GVend  —  • 


V total 


All  terms  are  defined  in  the  previous  section  except  V total,  which  for  NTSC 
video  is: 


V total  =  262.5  lines 
from  Figure  A-4. 


Starting  and  ending  positions  for  200-line  graphics 

Borrowing  from  the  previous  section,  the  starting  and  ending  positions  for 
200-line  graphics  as  proportions  of  total  V  are  simply: 

GVstart  =  =  0.1486  Vtotal 


GVend  =  2^  =  0.9105  Vtotal 

Starting  and  ending  positions  for  240-line  (640  x  480)  graphics 

Borrowing  from  the  previous  section,  the  starting  and  ending  positions  for 
240-line  graphics  as  proportions  of  total  V  are  simply: 

GVstart  =  ||^|  =  0.0714  Vtotal 
GVend  =  =  0.9857  VuAal 

Position  of  graphics  as  a  proportion  of  active  video 

To  calculate  the  position  of  graphics  as  a  proportion  of  active  vertical  timing 
using  the  nominal  start  of  video  as  a  reference,  simply  change  equations  11 
and  12  to  yield: 


(V active  —  Gactive ) 


(13)  GVstart  - 


Vactive 


(V active  -  Gactive) 


(14)  GVend  = 


+  Gactive 


Vactive 
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All  terms  are  defined  in  previous  sections  except  Vactiue,  which  for  NTSC 
video  is: 


Vactiue  —  241.5  liflCS 


from  Figure  A— 4. 


Starting  and  ending  positions  for  200-line  graphics 

Borrowing  from  previous  sections,  the  starting  and  ending  positions  for  200- 
line  graphics  as  proportions  of  active  V  are  simply: 

(241.5  -  200) 

GVgtart  — - nii  g - =  0-0859  Vactiue 

Z41.5 

(241^200)  +  2oo 

GVend  = - 242  5 - =  0-0141  Vactiue 

Starting  and  ending  positions  for  240-line  (640  x  480)  graphics 

Borrowing  from  previous  sections,  the  starting  and  ending  positions  for  240- 
line  graphics  as  proportions  of  active  V  are  simply: 

(241,5  -  240) 

GVstart  = - 2^h - =  00031  Vactivt 

(241^240)  +  240 

GVend  = - 242  5 - =  0.9969  Vactiue 


A.4.3  PAL 


Figure  A-5  shows  the  timing  for  15-kHz  PAL  video  including  the  position  of 
200-line  graphics.  The  timing  values  in  the  figure  are  either  taken  directly 
from  or  derived  from  the  accepted  standard  for  PAL  video.  The  calculations 
in  this  section  are  based  on  the  values  shown  in  the  figure. 
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Figure  A-5. 
PAL  vertical  timing 
with  200-line 
overlayed  graphics 


The  general  equations  used  to  calculate  graphics  positions  for  PAL  are  identi¬ 
cal  to  those  for  NTSC.  However,  the  values  used  for  the  equation  variables 
diffei  because  of  differences  in  vertical  timing.  For  convenience,  all  equations 
and  variable  values  are  repeated  in  the  following  section... 


Position  of  graphics  in  lines  relative  to  vertical  sync 

To  determine  the  correct  position  of  graphics  over  video  as  the  number  of 
lines  relative  to  vertical  sync  for  a  15.625-kHz,  PAL,  video  signal  given  the 
timing  shown  in  Figure  A-5,  use  the  following  equations  and  assumptions. 
Note  that  the  calculations  can  easily  be  modified  for  different  numbers  of 
graphics  lines. 

The  general  equation  for  the  starting  position  of  graphics  centered  in  active 
video  as  the  number  of  lines  relative  to  the  start  of  vertical  sync  can  be 
expressed  as: 


(15)  GV start  =AVsiart  +  ~ 

Similarly,  the  general  equation  for  the  ending  position  of  graphics  as  the 
number  of  lines  relative  to  the  start  of  vertical  sync  can  be  expressed  as: 


(16)  GVend  =  AVstort  +  ~  Gactlve)  +  Gactivt 

Where  GV  stands  for  “graphics  vertical,”  and  for  PAL  video: 
1.  The  nominal  start  of  active  video  is: 

AV start  =  22.5  lines 

from  Figure  A-5. 
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2.  The  number  of  active  video  lines  is: 

Vactive  —  287  5  lines 
from  Figure  A-5. 

3.  The  number  of  active  graphics  lines  is  either: 

G active  =  200  lines 

for  640  x  200  and  320  x  200  graphics,  or: 

G active  =  240  lines 

for  640  x  480  graphics  and  various  special  PAL  modes  (see  assumption  2 
in  Section  A.4.1.) 

Starting  and  ending  positions  for  200-line  graphics 

Solving  equation  15  for  the  start  of  200-line  graphics  yields: 

GVstart  =  22.5  +  287'52~  200  -  66  lines 
Solving  equation  16  for  the  end  of 200-line  graphics  yields 
GVend  =  22.5  +  287-52~2Q°  +  200  -  266  lines 

Starting  and  ending  positions  for  240-line  graphics 

Solving  equation  15  for  the  start  of  240-line  graphics  yields: 

GV gtart  =  22.5  + - - - “  46  lines 

Solving  equation  16  for  the  end  of 240-line  graphics  yields 
287  *5  —  240 

GVend  =  22.5  +  2  +  240  *  286  lines 

Position  of  graphics  as  a  proportion  of  total  video. 

To  calculate  the  position  of  graphics  as  a  proportion  of  total  vertical  timing, 
simply  change  equations  15  and  16  to  yield: 

AV start  +  —  ~  GacUue) 

(17)  GVetart  = - - - - 
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All  terms  are  defined  in  previous  sections  except  Vactive,  which  for  PAL 
video  is: 

Vactive  =  287.5  lines 
from  Figure  A-5. 

Starting  and  ending  positions  for  200-line  graphics 

Borrowing  from  previous  sections,  the  starting  and  ending  positions  for 
240-line  graphics  as  proportions  of  active  V  are  simply: 

(287.5  -  200) 

GV start  = - 287  5 - =  ^  Vactive 

(287-5- 200) +  20Q 

GVend  = - - =  0.8478  Vactive 

Starting  and  ending  positions  for  240-line  graphics 

Borrowing  from  previous  sections,  the  starting  and  ending  positions  for 
240-line  graphics  as  proportions  of  active  V  are  simply: 

(287.5  -  240) 

GV  start  — - ggY  g - —  0.0826  Vactive 

(287.5  -  240)  +  24q 

GVend  = - yg - 0.9174  Vactive 
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B  IBM  PC  and  compatible  graphics 
modes 


Table  B-l. 
IBM-compatible 
graphics  modes 


Table  B-l  lists  standard  graphics  modes  returned  by  BIOS  interrupt  10H, 
service  OFH  for  IBM  and  compatible  personal  computers.  Compliant  systems 
need  not  support  all  listed  modes  and  may  support  but  not  require  unlisted, 
nonstandard  modes.  However,  if  a  system  claims  support  for  a  listed  mode, 
the  mode  must  be  supported  as  listed.  Supporting  a  standard  mode  in  a  non¬ 
standard  manner  may  make  a  system  noncompliant. 

Note  that  modes  0-3  are  overlay  modes  for  all  adapter  types.  Therefore,  they 
are  restricted  to  200  lines  in  NTSC  and  PAL  video  modes  regardless  of  how 
many  lines  the  adapter  would  normally  use. 


Mode1 

(decimal) 

Type 

Resolution 

Colors 

Overlay 

mode 

Adapter2 

0,1 

Text 

40x25 

16 

Yes 

CGA,  EGA,  MCGA,  VGA 

2,3 

Text 

80x25 

16 

Yes 

CGA,  EGA,  MCGA,  VGA 

4,5 

Graphics 

320  x  200 

4 

Yes 

CGA,  EGA,  MCGA,  VGA 

6 

Graphics 

640  x  200 

2 

Yes 

CGA,  EGA,  MCGA,  VGA 

7 

Text 

80x25 

Mono 

No 

EGA,  VGA 

13 

Graphics 

320  x  200 

16 

Yes 

EGA,  VGA 

14 

Graphics 

640  x  200 

16 

Yes 

EGA,  VGA 

15 

Graphics 

640  x  350 

Mono 

No 

EGA,  VGA 

16 

Graphics 

640  x  350 

16 

No 

EGA,  VGA 

17 

Graphics 

640  x  480 

2 

Yes 

MCGA,  VGA 

18 

Graphics 

640  x  480 

16 

Yes 

VGA 

19 

Graphics 

320  x  200 

256 

Yes 

MCGA,  VGA 

’Does  not  include  modes  exclusive  to  the  IBM  PCjr  and  internal  BIOS  modes. 
2CGA  «  Color  Graphics  Adapter,  EGA  -  Enhanced  Graphics  Adapter,  MCGA  = 
Multicolor  Graphics  Array,  VGA  *  Video  Graphics  Array 
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Note:  An  application  written  for  a  compliant  system  based  on  one  adapter 
may  not  be  portable  to  a  compliant  system  based  on  a  different  adapter.  For 
example,  a  compliant  application  that  uses  mode  19  will  not  be  portable  to  a 
compliant  system  that  is  limited  to  EGA  modes. 

Any  system  that  requires  applications  to  use  a  nonstandard  graphics  mode  is 
noncompliant.  Any  application  that  uses  a  nonstandard  mode  is 
noncompliant. 


C  Application  programming  examples 


This  subsection  gives  several  brief  programming  examples  that  use  the 
ASCII  and  binary  interfaces.  The  examples  are  intended  only  to  furnish  a 
starting  point  for  programmers.  They  are  not  intended  to  be  overly  sophisti¬ 
cated  or  complete.  Therein  lies  the  makings  of  another  document. 


C.1  Using  the  ASCII  interface 


Even  programming  systems  with  minimal  facilities  for  interfacing  to  other 
languages  can  use  an  installable  device  driver.  The  two  short  programs  below 
use  the  Microsoft  GWBASIC  interpreter. 


For  clarity  and  brevity,  these  programs  do  not  determine  which  service  groups  are 
present  or  check  for  errors  after  issuing  commands.  However,  well-behaved 
applications  should  do  both. 


10  OPEN  ■0*>#1l*ivdev* 

20  PRINT  #1,  "sylnit" 

30  PRINT  #1,  "vmlnit* 

40  PRINT  #1,  "vdlnit" 

50  PRINT  #1,  "xylnit* 

50  PRINT  #1 , "vdPlay  start=1000,stop=2000,wait" 
60  CLOSE  #1 

70  OPEN  "I',#1,"ivdev" 

80  INPUT  #1 ,R$ 

90  CLOSE  #1 

100  IF  R$="0K"  THEN  PRINT  "Playing"  ELSE  PRINT 
" PROBLEMS 1  " ;R$ 

110  OPEN  "0",#1 , "ivdev" 

120  PRINT  #1,  "syStop" 

130  CLOSE  #1 
140  END 
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10  OPEN  "0" ,#1 , “ivdev* 

20  PRINT  #1,  "sylnit" 

30  PRINT  #1,  "vmlnit* 

40  PRINT  #1,  “vdlnit" 

50  PRINT  #1,  “xylnit* 

60  PRINT  #1,"vmGetPalette  color=5,r,g,b" 

70  CLOSE  #1 

80  OPEN  “I" ,#1, “ivdev- 
90  INPUT  #1 ,R$ 

100  CLOSE  #1 

110  REM  The  next  section  of  code  would  parse  R$,  which  is 
120  REM  in  the  form  ■<r  value>,<g  value>,<b  value>" 

•  •  • 

200  REM  Now  shut  it  down 
210  OPEN  "O’  ,#1,  'ivdeV 
220  PRINT  #1,  ■syStop" 

230  CLOSE  #1 
240  END 


C.2  Using  software  interrupt  calls 


Programming  systems  with  library  facilities  for  software  interrupts  can  use 
direct  software  interrupt  calls  for  issuing  commands.  The  following  example 
uses  Microsoft  C  5.1.  It  is  a  code  fragment,  not  a  complete  program,  and,  as 
such,  is  not  compilable. 

/* 

*  This  example  gets  the  values  for  a  logical  color. 

*  Obviously,  a  well- structured  program  would  hide  the 

*  interrupt  call  in  a  separate  function. 

*  The  example  omits  typical  start-up  and  shut-down  code 

*1 

#include  <stdio.h> 

^include  <dos.h> 

^define  VMGETPALETTE  2049 


#define  COLORPARM  9 
^define  RED  38 
tfdefine  GREEN  25 
ffdefine  BLUE  4 


struct  ivparm 

{ 

long  parm_id; 
long  parm_val; 

}  parras  12oT,  far  *p; 
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union  REGS  cpuregs; 
struct  SREGS  segregs; 

int  iv_int  =  0x60  I*  software  interrupt,  normally  *1 

/*  read  from  environment  */ 

/* 

*  The  following  code  fragment  would  be  included  in 

*  function  blocks 
*/ 

/*  initialize  far  pointer  */ 
p  =  parms; 

/*  Set  up  parameter  block  */ 

parms [0] .parm_id  =  COLORPARM; 
parms [0] .parm_val  =  5; 
parms [ 1 ] . parm_id  »  RED ; 
parms[2] .parm_id  =  GREEN; 
parms[3] .parm_id  =  BLUE; 

/* 

*  Set  up  CPU  registers  and  call  software  interrupt. 

*  cpuregs  and  segregs  are  structures  for  manipulating 

*  CPU  registers.  FPjOFF  and  FP_SEG  are  macros  that 

*  find  the  absolute  address  of  a  variable. 

*/ 

cpuregs. x. ax  =  VMGETPALETTE; 

cpuregs. x.bx  =  4;  /*  number  of  parameters  */ 

cpuregs. x.di  =  FP_0FF(p); 
segregs.es  =  FP_SEG(p); 

/* 

*  int86x()  is  an  MSC  library  function  that  calls 

*  a  software  interrupt. 

*/ 

int86x(iv_int,  &cpuregs,  &cpuregs,  &segregs); 

/*  Check  for  errors  */ 

if  (cpuregs. x. ax  1=  0) 

{ 

printf( ’Error  code;  %d\n’,  (int)  cpuregs. x. ax) ; 
exit ( 1 ) ; 

> 

/*  Print  the  color  values  */ 

printf ("Color  5  Red .Green, Blue  %d,%d,%d\n’, 

(int)  parms(1 ] .parm_val,  (int)  parms[2] .parm_val, 

(int)  parms[3] .parm_val) ; 
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C.3  Library  calls  with  parameter  numbers 


Vendors  may  furnish  libraries  for  specific  languages  that  use  parameter  num¬ 
bers  of  the  binary  interface  stored  in  a  data  structure  appropriate  to  the  lan¬ 
guage.  Several  languages  support  functions  that  accept  variable  numbers  of 
parameters.  The  following  example  uses  Microsoft  C  5. 1  to  show  how  to  use 
variable  numbers  of  parameters  to  set  up  a  parameter  block.  It  omits  the 
code  that  would  then  execute  the  function. 


#include  <stdio.h> 

#include  <stdarg.h>  /*  for  ANSI  compatibility  */ 

/* 

*  This  function  might  be  part  of  a  support  library. 

*  va_start()  and  va_arg()  are  macros  for  accessing 

*  variable -length  argument  lists. 

*  (See  MSC  5.1  manuals  for  details.) 

*/ 


iv_vdplay(long  parml ,  . . . ) 

{ 

va_list  argp; 
struct  ivparm 
{ 

long  parm_id; 
long  parm_val; 

}  parms  [20]; 
int  i; 

va_start(argp,  parml); 

/*  Set  up  parameter  block  from  variable  arg  list  *1 

for(i  -  0;  parms[i)  ,parm_id  1=  NL’lL  &&  i  <  20;  i++) 
{ 

parms [ i] .parm_id  =  va_arg(argp,  long); 
parms [ ij .parm_val  =  va_arg(argp,  long); 

> 


/*  Now  insert  rest  of  code  to  execute  command  */] 


•  •  ■ 

} 
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C.4  Analyzing  bit  fields 


It  is  simple  to  analyze  bit  fields  with  any  language  that  supports  bit-wise 
“and”.  The  following  example  uses  the  Microsoft  GWBASIC  interpreter. 

100  REM  Start  by  initializing  the  system 
110  OPEN  "0" ,#1 , "ivdev" 

120  PRINT  #1 , “sylnit" 

130  CLOSE  #1 

140  OPEN  "I" ,#1 , "ivdev" 

150  INPUT  #1,R$ 

160  CLOSE  #1 

170  IF  R$  <>  “0K“  THEN  PRINT  "Cannot  initialize  system” 
:G0T0  300 

180  REM  Now  request  the  support  information 
190  OPEN  “0" ,#1 , "ivdev" 

200  PRINT  #1 , "syGetState* 

210  CLOSE  #1 

220  OPEN  "I“,#1, "ivdev" 

230  INPUT  #1,R$ 

240  CLOSE  #1 

250  REM  R$  now  contains  the  decimal  string  which 
260  represents  the  support  bit  field 
2"r0  R=VAL(R$) 

280  REM  Do  the  "AND"  to  check  whether  xy  is  supported 
290  IF  R  AND  8  THEN  PRINT  "XY  input  is  supported" 

ELSE  PRINT  "XY  input  is  not  supported" 

300  OPEN  "0",#1," ivdev" 

310  PRINT  #1 , "syStop" 

320  CLOSE  #1 
330  END 
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D  Error  handling 


When  an  application  issues  a  command,  VDI  Management  may  be  unable  to 
carry  out  the  requested  action  or  return  the  requested  information.  This 
causes  an  error.  This  appendix  describes  the  error  codes  that  VDI  Manage¬ 
ment  can  return  to  an  application. 


D.1  General  information 


The  ASCII  interface  returns  errors  as  response  strings  consisting  of  the  word 
“ERROR”  followed  by  a  space  and  the  error  number.  For  example,  “ERROR 
49”  signals  that  a  command  included  insufficient  parameters.  The  binary 
interface  returns  error  numbers  in  the  microprocessor’s  AX  register  on  return 
from  the  software  interrupt  (AX=0  indicates  success). 

Some  VDI  Management  implementations  may  not  use  all  the  error  codes.  For 
example,  a  system  that  does  not  use  the  MS-DOS  filing  system  probably 
would  not  use  the  filing-system  error  codes.1  However,  implementors  should 
try  to  be  complete  and  should  not  omit  error  codes  simply  for  convenience. 


VDI  Management  implementations  may  supply  textual  error  messages.  (See 
syErrorMsg  in  Section  6.)  Although  this  is  not  a  compliance  requirement,  if  an 
implementation  does  support  textual  error  messages,  it  must  use  the  summary 
messages  given  in  this  appendix.  Although  this  appendix  presents  summary 
messages  in  mixed  case  for  legibility,  VDI  Management  returns  summary  mes- 
sages  (and  all  other  return  strings)  in  all  capital  letters. 


VDI  Management  should  try  to  recover  before  returning  an  error  response  to 
the  application.  For  example,  if  a  communications  error  occurs,  VDI  Manage¬ 
ment  should  return  an  error  only  after  repeated  retries  have  failed. 


1  Filing-system  error  codes  are  included  primarily  for  use  by  future  digital  audio  commands. 
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Note:  VDI  Management  cannot  handle  the  error  of  a  user  forgetting  to  in¬ 
stall  VDI  Management  or  the  correct  interface  used  by  an  application.  Appli¬ 
cations  should  guard  against  this  by  confirming  that  VDI  Management  and 
the  proper  interface  are  installed  (see  Sections  3.2.2  and  3.3.2). 


D.2  Error  listings 


The  following  subsections  list  error  numbers  in  numerical  order  with  sum¬ 
mary  messages  and  brief  explanations.  Related  errors  are  grouped  for  con¬ 
venience  and  do  not  necessarily  imply  a  corresponding  programming 
structure  in  VDI  Management  implementations.  However,  implementations 
should  use  the  error  numbers  as  they  are  defined. 


D.2.1  Command  problems 


1  Service  group  not  installed _ 

The  VDI  implementation  supports  the  service  group  that  contains  the  com¬ 
mand,  but  the  service  group  is  not  installed.  For  example,  an  application  is¬ 
sued  an  xy  command  on  a  system  that  is  not  configured  for  XY-input  devices 


2  Unknown  command 

The  command  does  not  exist. 


Compliant  VDI  implementations  cannot  return  this  error  in  response  to  any  core 
command  for  a  supported  service  group. 


3  System  not  initialized 


The  command  was  issued  before  the  application  issued  sylnit,  or  syStop 
was  followed  by  a  command  other  than  sylnit. 


15  General  command  error 


A  command  error  occurred  that  is  not  listed  above  or  about  which  no  informa¬ 
tion  is  available. 
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When  an  application  issues  a  command,  VDI  Management  may  be  unable  to 
carry  out  the  requested  action  or  return  the  requested  information.  This 
causes  an  error.  This  appendix  describes  the  error  codes  that  VDI  Manage¬ 
ment  can  return  to  an  application. 


D.1  General  information 


The  ASCII  interface  returns  errors  as  response  strings  consisting  of  the  word 
“ERROR”  followed  by  a  space  and  the  error  number.  For  example,  “ERROR 
49”  signals  that  a  command  included  insufficient  parameters.  The  binary 
interface  returns  error  numbers  in  the  microprocessor’s  AX  register  on  return 
from  the  software  interrupt  (AX=0  indicates  success). 

Some  VDI  Management  implementations  may  not  use  all  the  error  codes.  For 
example,  a  system  that  does  not  use  the  MS-DOS  filing  system  probably 
would  not  use  the  filing-system  error  codes.1  However,  implementors  should 
try  to  be  complete  and  should  not  omit  error  codes  simply  for  convenience. 


VDI  Management  implementations  may  supply  textual  error  messages.  (See 
syErrorMsg  in  Section  6.)  Although  this  is  not  a  compliance  requirement,  if  an 
implementation  does  support  textual  error  messages,  it  must  use  the  summary 
messages  given  in  this  appendix.  Although  this  appendix  presents  summary 
messages  in  mixed  case  tor  legibility,  VDI  Management  returns  summary  mes¬ 
sages  (and  all  other  return  strings)  in  all  capital  letters. _ 


VDI  Management  should  try  to  recover  before  returning  an  error  response  to 
the  application.  For  example,  if  a  communications  error  occurs,  VDI  Manage¬ 
ment  should  return  an  error  only  after  repeated  retries  have  failed. 


1  Filing-system  error  codes  are  included  primarily  for  use  by  future  digital  audio  commands. 
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Note:  VDI  Management  cannot  handle  the  error  of  a  user  forgetting  to  in¬ 
stall  VDI  Management  or  the  correct  interface  used  by  an  application.  Appli-  # 

cations  should  guard  against  this  by  confirming  that  VDI  Management  and 
the  proper  interface  are  installed  (see  Sections  3.2.2  and  3.3.2). 


D.2  Error  listings 


The  following  subsections  list  error  numbers  in  numerical  order  with  sum¬ 
mary  messages  and  brief  explanations.  Related  errors  are  grouped  for  con¬ 
venience  and  do  not  necessarily  imply  a  corresponding  programming 
structure  in  VDI  Management  implementations.  However,  implementations 
should  use  the  error  numbers  as  they  are  defined. 


D.2.1  Command  problems 


1  Service  group  not  installed 


The  VDI  implementation  supports  the  service  group  that  contains  the  com¬ 
mand,  but  the  service  group  is  not  installed.  For  example,  an  application  is¬ 
sued  an  xy  command  on  a  system  that  is  not  configured  for  XY-input  devices.  • 

2  Unknown  command 


The  command  does  not  exist. 


Compliant  VDI  implementations  cannot  return  this  error  in  response  to  any  core 
command  tor  a  supported  service  group. 


3  System  not  initialized 


The  command  was  issued  before  the  application  issued  sylnit,  or  syStop 
was  followed  by  a  command  other  than  sylnit. 


15  General  command  error 


A  command  error  occurred  that  is  not  listed  above  or  about  which  no  informa¬ 
tion  is  available. 
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D.2.2  ASCII  interface  problems 


16  Bad  command  syntax _ 

The  parser  encountered  a  fatal  syntax  error  that  could  not  be  further  diag¬ 
nosed.  For  example,  a  command  string  contained  a  control  code. 


Error  16  should  not  be  used  in  place  of  parameter-problems  errors  (see  Sec¬ 
tion  D.2.4). 


17  Command  too  long _ 

The  command  was  longer  than  255  characters  and  will  be  ignored  in  its  en¬ 
tirety.  (The  terminal  carriage  return  counts  but  redundant  delimiters  do  not.) 

18  Response  too  long _ 

The  response  to  an  information  request  including  the  terminal  CR/LF  would 
be  longer  than  255  characters.  VDI  Management  does  not  return  partially 
filled  information  requests.  For  example,  the  application  used  an  xxGet- 
State  command  to  request  too  much  information. 

19  Device  driver  read  before  write _ 

The  application  tried  to  read  a  response  from  the  device  driver  before  it  had 
written  at  least  one  command  to  it.  This  is  illegal  and  indicates  a  problem 
with  the  application’s  initialization  code. 

This  error  can  occur  only  immediately  after  VDI  Management  has  been  in¬ 
stalled  or  after  a  well-behaved  application  has  issued  an  syStop  before 
exiting. 


31  General  ASCII  interface  error _ 

An  ASCII  interface  error  has  occurred  that  is  not  listed  above  or  about  which 
no  information  is  available. 

P.2.3  Binary  interface  problems 


32  Invalid  parameter  count _ 

On  80x86-based  systems,  the  BX  register  contains  an  invalid  or  out  of  range 
parameter  count.  For  example,  the  application  passed  a  negative  value  in  BX. 
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33  Invalid  parameter  packet  address _ 

On  80x86-based  systems,  the  ES:DI  register  pair  contains  an  invalid  address 
for  a  parameter  packet. 

34  Invalid  pointer  in  parameter  packet _ 

The  parameter  packet  contains  a  null  or  invalid  pointer. 

47  General  binary  interface  error _ 

A  binary  interface  error  occurred  that  is  not  listed  above  or  about  which  no  in¬ 
formation  is  available. 

P.2.4  Parameter  problems 


48  Unknown  parameter _ 

The  command  included  a  parameter  label  that  is  not  valid  for  any  command. 


Compliant  VDI  implementations  cannot  return  this  error  in  response  to  any  core 
parameter  for  a  supported  service  group. 


49  Insufficient  parameters _ 

The  command  required:  a  specific  parameter  that  was  missing;  at  least  one 
parameter  from  a  specific  group  of  parameters  and  was  issued  without  the  pa¬ 
rameter;  or  at  least  one  parameter  that  could  have  been  any  parameter  in  its 
list  and  was  issued  with  no  parameters. 

50  Parameters  cannot  be  used  together _ 

The  command  included  two  or  more  parameters  that  cannot  be  used  together. 
For  example,  a  vdPlay  command  included  both  a  direction  and  a  to 
parameter. 

51  Parameter  value  Invalid  or  out  of  range _ 

The  command  included  an  incorrect  parameter  value.  For  example,  a  parame¬ 
ter  value  that  must  be  in  the  range  0-255  was  negative  or  greater  than  255. 

This  error  can  result  from  the  combined  effects  of  two  or  more  parameters 
and  from  exceeding  limits  set  by  another  parameter.  For  example,  with  the 
vmSetPalette  command  the  sum  of  the  color  and  length  parameters  must 
be  less  than  or  equal  to  logcolors  plus  one.  (Logcolors  is  the  maximum 
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number  of  available  logical  colors,  which  can  be  retrieved  with  the  vmGet- 
State  command.) 

52  Parameter  invalid  for  this  command _ 

The  command  included  a  known  but  invalid  parameter.  For  example,  the  ap¬ 
plication  issued  sylnit  with  a  color  parameter. 

53  Missing  parameter  value _ 

The  command  failed  to  include  a  value  for  a  parameter  that  requires  one.  The 
parser  reached  either  the  end  of  the  command  string  or  another  parameter 
label  when  a  parameter  value  was  expected. 

This  is  an  ASCII  interface  error  only. 

54  Parameter  used  more  than  once _ 

The  command  included  the  same  parameter  more  than  once.  This  is  never 
allowed. 

79  General  parameter  error _ 

A  parameter  error  occurred  that  is  not  listed  above  or  about  which  no  infor¬ 
mation  is  available. 

D.2.5  Hardware  problems  _ 


80  Initialization  error _ 

The  system  could  not  initialize  an  attached  device.  The  application  can  find 
out  which  device  by  examining  the  failed  command. 

81  Device  not  initialized _ 

The  application  tried  to  use  either  an  uninitialized  device  or  an  uninitialized 
service  group. 

82  Communications  timeout _ 

A  timeout  occurred  while  VDI  Management  was  communicating  with  a  pe¬ 
ripheral  device.  Either  the  device  did  not  produce  an  expected  message 
within  a  predetermined  timeout  period,  or  the  computer  was  unable  to  send  a 
message  to  the  device  because  signal  control  lines  were  in  an  ippropriate 
state.  For  example,  this  error  would  result  from  a  cable  being  unplugged 
after  a  device  has  been  initialized. 
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83  Communications  error _ _ 

An  error  occurred  during  communications.  For  example,  repeated  parity  er¬ 
rors  that  cannot  be  cleared  during  asynchronous  serial  communications 
cause  this  error. 

84  Device  reports  error _ 

A  peripheral  device  sent  a  message  indicating  that  an  error  occurred  that  it 
cannot  clear. 

85  Device  canceled  request _ 

A  peripheral  device  sent  a  message  indicating  that  it  has  unilaterally  can¬ 
celed  a  requested  service. 

86  Device  not  ready _ 

A  peripheral  device  sent  a  message  indicating  that  it  cannot  be  made 
operational. 

87  Action  not  supported  by  device _ 

A  peripheral  device  sent  a  message  indicating  that  it  cannot  do  a  requested 
action.  This  error  indicates  either  an  installation  problem  or  the  inappro¬ 
priate  use  of  the  vdPassThru  command.  Compliant  systems  should  not  nor¬ 
mally  generate  this  error. 

88  Unable  to  return  requested  information _ 

A  hardware  device  could  not  generate  information  requested  by  a  command. 
For  example,  a  CLV  videodisc  could  not  report  a  frame  number. 

Ill  General  hardware  error _ 

A  hardware  error  occurred  that  is  not  listed  above  or  about  which  no  informa¬ 
tion  is  available. 

D.2.6  System  resources 


Some  systems  may  not  be  able  to  return  some  errors  in  this  group. 


112  Insufficient  memory _ 

VDI  Management  could  not  access  enough  memory  to  perform  the  requested 
service. 
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113  Needed  hardware  interrupt  in  use _ 

VDI  Management  requires  the  use  of  a  specific  hardware  interrupt  that  is  al¬ 
ready  in  use,  or  one  of  a  range  of  interrupts  and  all  are  in  use. 

114  Needed  software  interrupt  in  use _ 

VDI  Management  requires  the  use  of  a  specific  software  interrupt  that  is  al¬ 
ready  in  use,  or  one  of  a  range  of  interrupts  and  all  are  in  use. 

115  Needed  DMA  channel  not  available _ 

VDI  Management  requires  the  use  of  a  specific  DMA  channel  that  is  already 
in  use,  or  requires  the  use  of  any  DMA  channel  and  all  are  in  use. 


116  Needed  timer  not  available _ 

VDI  Management  requires  the  use  of  a  timer  resource  that  is  not  available. 


127  General  resources  error _ 

VDI  Management  requires  additional  system  resources  that  are  not  listed 
above  or  about  which  no  information  is  available. 

D.2.7  Filing  system  problems _ 


128  Invalid  filename _ 

The  command  used  a  filename  that  was  invalid  for  the  operating  system.  (A 
legal  filename  that  cannot  be  opened  should  return  error  132.) 

129  Invalid  path _ 

The  command  used  a  path  name  that  was  invalid  for  the  operating  system. 

130  invalid  drive _ 

The  command  specified  a  drive  that  is  not  recognized  by  the  operating  system. 

131  Invalid  file  number _ 

The  command  used  a  file  number  that  was  not  recognized  by  the  operating 
system. 

132  Cannot  open  or  create  file _ 

The  operating  system  could  not  open  or  create  a  requested  file. 
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133  Cannot  close  file 


The  operating  system  could  not  close  a  requested  file. 

134  File  already  open _ 

The  command  tried  to  open  a  file  that  was  already  open. 

135  File  already  exists _ 

The  command  tried  to  create  a  file  that  already  exists. 


136  File  does  not  exist _ 

The  command  tried  to  access  a  file  that  does  not  exist. 

137  File  access  denied _ 

The  command  was  denied  access  to  a  requested  file.  For  example,  a  file  with 
a  locked  status  on  a  network  file  server  would  cause  this  error. 

138  File  seek  error _ 

The  command  tried  to  use  a  nonexistent  piece  of  a  file.  For  example,  a  com¬ 
mand  tried  to  access  byte  9000  of  a  5-KB  file. 

139  Too  many  open  files _ 

The  operating  system  has  run  out  of  file  handles  because  too  many  files  are 
open.  Either  the  application  should  open  fewer  files  or  the  user  should 
change  the  operating  system  installation  to  allow  more  files  to  be  open 
simultaneously. 

140  Disk  full _ 

The  command  tried  to  write  to  a  full  disk.  The  user  should  delete  some  files 
or  change  to  a  different  disk  before  tTying  to  run  the  application  again. 


141  Disk  read  error _ 

A  data  error  occurred  while  reading  the  disk. 


142  Disk  write  error _ 

A  data  error  occurred  while  writing  to  the  disk. 
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159  General  filing-system  error _ 

A  filing-system  error  occurred  that  is  not  listed  above  or  about  which  no  infor¬ 
mation  is  available. 

D.2.8  Miscellaneous  problems _ 


160  Invalid  device  number _ 

The  command  specified  an  invalid  device  or  source  number.  This  error  re¬ 
sults  from  using  an  invalid  number  for  a  device  or  source  parameter  or  from 
trying  to  change  the  default  device  or  source  to  an  invalid  number. 


161  Buffer  overflow _ 

An  internal  VDI  Management  buffer  overflowed.  This  indicates  an  internal 
VDI  Management  failure  and  should  be  brought  to  the  attention  of  the  sys¬ 
tem  vendor. 

162  Internal  calculation  error _ 

An  error  such  as  divide  by  zero  occurred  during  a  numeric  calculation  within 
VDI  Management.  This  indicates  an  internal  VDI  Management  failure  and 
should  be  brought  to  the  attention  of  the  system  vendor. 

163  Copy  protection  error _ 

A  copy  protected  version  of  VDI  Management  has  declined  to  run  because  its 
protection  scheme  has  been  violated.  Legitimate  users  should  discuss  this 
problem  with  the  system  vendor. 

173  General  internal  error _ 

An  internal  VDI  Management  error  occurred  that  is  not  listed  above  or  about 
which  no  information  is  available.  This  indicates  an  internal  VDI  Manage¬ 
ment  failure  and  should  be  brought  to  the  attention  of  the  system  vendor. 

174  General  operating  system  error _ 

The  operating  system  reported  an  error  unrelated  to  the  filing  system  and 
not  specific  to  any  particular  aspect  of  VDI  Management.  (VDI  Management 
should  try  to  recover  firom  this  error  before  returning  it  to  the  application.) 

175  General  error _ 

An  error  occurred  that  is  not  listed  elsewhere  and  about  which  no  informa¬ 
tion  at  all  is  available. 
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This  error  differs  from  error  111  (General  hardware  error)  in  that  error  111 
guarantees  that  a  hardware  error  has  occurred  while  this  error  can  be  caused 
by  any  unknown  failure  including  unknown  hardware,  VDI  Management, 
and  application  failures. 


VDI  implementors  should  not  use  this  error  number  before  carefully  considering 
whether  a  more  informative  error  code  could  be  used.  This  is  an  error  of  last  resort. 


D.2.9  System  group  problems 


176  Queue  full _ 

The  application  tried  to  queue  more  than  10  commands.  This  indicates  an  ap¬ 
plication  problem  such  as  failing  to  turn  syQueue  off  at  the  appropriate  time. 

177  Command  cannot  be  queued _ 

The  application  tried  to  queue  a  command  that  cannot  be  queued.  This  indi¬ 
cates  an  application  problem  such  as  failing  to  turn  syQueue  off  at  the  appro¬ 
priate  time. 

191  General  system  error _ 

A  problem  occurred  within  the  system  {(roup  that  is  not  listed  above  or  about 
which  no  further  information  is  available. 

D.2.10  Visual-management  problems 


192  Synchronization  error _ 

The  video  signal  could  not  be  genlocked  to  the  computer’s  graphics  because 
the  signal  has  an  inappropriate  scan  rate.  Overlay  is  not  possible. 

193  Graphics  mode  problem _ 

The  system  could  not  do  a  requested  action  because  the  graphics  mode  does 
not  support  it.  For  example,  the  application  tried  to  turn  on  transparency  in  a 
graphics  mode  that  does  not  support  overlays. 

194  Unsupported  graphics  mode _ 

The  system  could  not  switch  to  a  requested  graphics  mode  or  emulation  state 
because  the  hardware  does  not  support  the  mode.  For  example,  issuing 
vmSetGraphics  emulation*0,  which  requires  a  VGA  adapter,  on  a  CGA  or 
EGA  system,  or  issuing  vmSetGraphics  mode»14,  which  requires  an  EGA 
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graphics  adapter,  on  a  CGA  system  would  cause  this  error.  (See  Appendix  A 
for  more  information  on  VGA  native  and  emulation  modes.) 

207  General  visual-management  error _ 

A  problem  occurred  with  the  visual  management  functions  that  is  not  listed 
above  or  about  which  no  further  information  is  available. 


D.2.11  Videodisc  problems 


208  Action  not  supported  by  disc _ 

The  command  requested  an  action  that  is  not  supported  by  the  videodisc.  For 
example  the  application  tried  to  do  a  frame  search  on  a  CLV  videodisc  or  a 
chapter  search  on  a  videodisc  that  without  chapter  stops. 


209  Disc  not  spun  up _ 

The  application  issued  a  command  such  as  vdPlay  that  requires  the  video¬ 
disc  to  be  spun  up  when  it  has  not  been  spun  up. 


210  Disc  not  spun  down _ 

The  application  issued  a  command  such  as  vdSet  door*l  thaf  requires  the 
videodisc  to  be  spun  down  when  it  has  not  been  spun  down. 


21 1  Door  open _ 

The  application  issued  a  videodisc  motion  command  other  than  vdSet 
door»0  with  the  player  door  open.  Typically,  this  is  a  user  error  that  can  be 
corrected  without  exiting  the  application. 


212  No  disc  in  tray _ 

The  application  issued  a  videodisc  motion  command  other  than  vdSet 
dooral  with  the  player  door  closed  but  without  a  videodisc  in  the  tray.  Typi¬ 
cally,  this  is  a  user  error  that  can  be  corrected  without  exiting  the  application. 


213  Bad  disc  section 


It  was  impossible  to  seek  to  the  required  frame  because  of  a  physical  problem 
with  the  videodisc. 
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214  Fell  off  disc _ 

An  attempt  was  made  to  play  backward  past  the  beginning  or  forward  past 
the  end  of  the  videodisc.  This  normally  indicates  improper  use  of  a  videodisc 
motion  command. 

215  Invalid  frame  number _ 

The  command  specified  a  frame  that  is  not  present  on  the  videodisc. 

216  Invalid  chapter  number _ 

The  command  specified  a  chapter  that  is  not  present  on  the  videodisc. 


217  Invalid  time  code _ 

The  command  specified  a  time  code  that  is  not  present  on  the  videodisc. 

239  General  videodisc  player  error _ 

A  videodisc  error  occurred  that  is  not  listed  above  or  about  which  no  informa¬ 
tion  is  available. 

D.2.12  XY-input  device  problems _ 


240  Device  not  calibrated _ 

A  required,  implementation-specific,  calibration  process  has  not  been  done. 
The  user  should  verify  that  the  XY-input  device  is  installed  correctly. 


241  invalid  coordinate _ 

A  coordinate  was  specified  that  is  outside  the  acceptable  range.  This  nor¬ 
mally  indicates  an  application  problem. 

242  Cursor  problem _ 

A  problem  with  the  graphics  device  caused  a  cursor  display  problem.  This  in¬ 
dicates  that  the  application  requires  a  facility  that  VDI  Management  does 
not  furnish. 

255  General  XY-input  error _ 

An  XY-input  error  occurred  that  is  not  listed  above  or  about  which  no  infor¬ 
mation  is  available. 
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command  parameter 
syCheckError,  6-3 
command  queue 
See:  syQueue 
command  strings,  3-8 
buffering,  4-8 
delimiters,  4-5 
length  limits,  4-5-4-6 
syntax,  4-5~4-6 
terminator,  4-4 
tokens,  4-4 
commands 

See  also:  individual  command  name  entries 

ASCII  name  summary,  5-3 

binary  token  number  summary,  5-3 

core,  2-4-2-5, 5-3 

deriving  token  numbers,  5-2 

extended,  2-4-2-5, 5-3 

format  of  names,  1-4 


mixing  ASCII  and  binary,  3-9 
organization,  2-4 
prefix  values,  5-1 
system  (sy)  summary,  6-1 
unqueueable,  6-16 
videodisc  (vd)  summary,  8-1 
visual-management  (vm)  summary,  7-1 
word  values,  5-2 
XY-input  (xy)  summary,  9-1 
comments 

See  also:  ASCII  interface 
submission  procedure,  1-5 
compatibility 

See:  compliance  requirements 
See:  device  interoperability 
See:  platform  independence 
See:  portability 
compliance  requirements 
core  commands,  2-4 
core  parameters,  2-4 
device  numbers,  4-2 
dynamic  repositioning  of  graphics,  A-l 
error  messages,  D-l 
extended  commands,  2-5 
extended  parameters,  2-5 
fade  and  dissolve  levels,  7-4 
graphics  adapters,  B-2 
graphics  modes  zero  through  three,  7-3,  B-l 
IBM  graphics  modes,  B-l 
interface  installation,  4-1 
interface  provision,  3-9 
MS-DOS  versions,  4-3 
service  group  provision,  2-4 
system  (sy)  commands,  6-1 
transparent  colors,  7-31 
VGA  emulation  of  CGA/EGA,  7-4 
VGA  emulation  of  CGA/EGA  graphics,  A-3-A-4 
videodisc  (vd)  commands,  8-1 
videodisc  types,  8-2 

visual-management  (vm)  commands,  7-1 
XY-input  (xy)  commands,  9-1 
constant  angular  velocity 
See:  videodiscs 
constant  linear  velocity 
See:  videodiscs 
cooked  mode,  4-9 
coordinate  space 

See:  XY-coordinate  space 
See:  xyGet 
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See:  xySet 
core  commands 
See:  commands 
See:  compliance  requirements 
core  parameters 

See:  compliance  requirements 
See:  parameters 
critical  section  flag,  4-3 
cursor 

See:  XY-input  devices 
cursor  keypad 

See:  XY-input  devices 
cursor  parameter 
xyGetState,  9-9 
xySet,  9-17 


D 

decimal  numeric  format,  1-4 
defdevice  parameter 
vdGetState,  8-7 
vdSet,  8-32 
xyGetState,  9-9 
xySet,  9-17 
defsource  parameter 
vmGetState,  7-17 
vmSetVideo,  7-33 
design  criteria 
See:  interfaces 
device  driver,  2-3,  3-1 
See  also:  ASCII  interface 
See  also:  IVDEV 
buffer  behavior,  4-8 
communications,  3-7 
duplicate  file  names,  3-8 
IOCTL  functions,  4-9 
modes,  4-9 

MS-DOS  version  requirements,  4-3 
name,  3-7 

reentrancy  issues,  4-4 
device  interoperability,  1-1 
device  numbers,  2-4, 4-2,  9- 1-9-2 
See  also:  defdevice  parameter 
See  also:  device  parameter 
See  also:  source  numbers 
See  also:  tdevices  parameter 
See  also:  vdSet 
See  also:  xySet 
default,  6-12 


mapping  logical  to  physical,  4-2 
rules,  4-2 

stating  requirements,  4-2 
device  parameter 
vdGetState,  8-7 
vdlnit,  8-12 
vdPassThru,  8-16 
vdPlay,  8-19 
vdScan,  8-25 
vdSearch,  8-28 
vdSet,  8-32 
vdStep,  8-35 
vdStill,  8-37 
xyGetlnput,  9-5 
xyGetState,  9-9 
xylnit,  9-12 
xySet,  9-17 
DI  register 

See:  Intel  80x86 
direction  parameter,  8-20 
vdPlay,  8-19 
vdScan,  8-25 
vdStep,  8-36 
disc 

See:  videodiscs 
disc  player 

See:  videodisc  players 
disctype  parameter 
vdGetState,  8-7 
display  screen,  A-2 
display  width 

See:  width  parameter 
dissolve  level  control 
See:  dlevel  parameter 
See:  vmFade 
dissolve  unit 

See:  video  overlay  subsystem 
dissolves 
See:  rounding 
See:  vmFade 
dlevel  parameter 
default,  7-21 
vmFade,  7-7 
vmGetState,  7-17 
door  parameter 
default,  8-12 
vdGetState,  8-8 
vdSet,  8-32 
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E 

EGA 

See  also:  graphics  adapter 

active  graphics  area,  A-3-A-4 

background  video,  A-3 

graphics  position  reference,  A-3 

horizontal  registration  to  NTSC  video,  A-5-A-7 

horizontal  registration  to  PAL  video,  A-8-A-10 

line  width,  A-4 

pixel  size,  A-4 

reference  signal,  A-4 

standard  modes,  B-l 

vertical  registration  to  NTSC  video,  A-12-A-15 
vertical  registration  to  PAL  video,  A-16-A-19 
emulation  parameter 
default,  7-21 
vmGetState,  7-17 
vmSetGraphics,  7-24 
enable  parameter 
default,  7-21 
vmGetState,  7-17 
vmSetTrans,  7-31 
Enhanced  Graphics  Adapter 
See:  EGA 

environment  variable 
See:  IVINT 
errno  parameter 
syCheckError,  6-4 
syErrorMsg,  6-6 
error  messages 
ASCII  interface,  D-3 
binary  interface,  D-3-D-4 
commands,  D-2 
filing  system,  D-7-D-9 
hardware,  D-5-D-6 
miscellaneous,  D-9-D-10 
parameters,  D-4-D-5 
system  group,  D-10 
system  resources,  D-6-D-7 
videodisc,  D-ll-D-12 
visual  management,  D-10-D-11 
XY-input  device,  D-12 
errors 

See  also:  ASCII  interface 
See  also:  binary  interface 
See  also:  Intel  80x86,  AX  register 
See  also:  response  strings 
buffering,  6-3 

from  queued  commands,  6-16 


nonimmediate,  6-2 
retrieving  descriptions,  6-6 
retrieving  most  recent,  6-2 
ES  register 

See:  Intel  80x86 
execute  parameter 
syQueue,  6-15 
extended  commands 
See:  commands 
extended  parameters 
See:  parameters 


F 

fader 

See:  video  overlay  subsystem 
fades 

See:  rounding 
See:  vmFade 
field 

See:  videodiscs 
file 

control  blocks,  4-9 
handles,  4-9 
frame 

See:  frame  parameter 
See:  videodiscs 
frame  number  display 
See:  idxdisplay  parameter 
See:  vdSet 
frame  parameter 
default,  8-12 
vdGetState,  8-8 
vdSearch,  8-28 
frame  search 

See:  from  parameter 
See:  vdSearch 
from  parameter 
vdPlay,  8-20 


G 

g  parameter 

vmGetPalette,  7-12 
vmSetPalette,  7-27 
genlock  control 

See:  visual  management 
glevel  parameter 
default,  7-21 
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vmFade,  7-8 
vmGetState,  7-17 
gmode  parameter 
default,  7-21 
vmGetState,  7-18 
vmSetGraphics,  7-24 
graphics  adapter,  7-3-7-4 
See  also:  CGA 
See  also:  EGA 
See  also:  VGA 
requirements,  2-2 
graphics  cursor 

See:  XY-input  device 
graphics  horizontal  line  length,  A-4 
graphics  level  control 
See:  glevel  parameter 
See:  vmFade 

graphics  modes,  7-2-7-3,  B-l-B-2 
See  also:  gmode  parameter 
See  also:  vmSetGraphics 
graphics  position  relative  to  video 
See:  graphics  registration 
graphics  registration,  7-3,  A-l-A-19 
See  also:  vmSetGraphics 
See  also:  width  parameter 
See  also:  xoffset  parameter 
See  also:  yoffset  parameter 
horizontal,  A-4-A-10 
reference  frame,  A-l 
terms  of  reference,  A-2 
vertical,  A-ll-A-19 
graphics  resolution,  A-4 
See  also:  horzpix  parameter 
See  also:  vertpix  parameter 
green 

See:  g  parameter 


H 

hardware  requirements,  2-2 
hexadecimal  numeric  format,  1-4 
horizontal  blanking 
See:  blanking 
horizontal  sync 
See:  sync  signals 
horzpix  parameter 
default,  7-21 
vmGetState,  7-18 


I 

idxdisplay  parameter 
default,  8-12 
vdGetState,  8-8 
vdSet,  8-32 
initialization 
See:  sylnit 
See:  vdlnit 
See:  vmlnit 
See:  xylnit 

installable  device  driver 
See:  device  driver 
installation 

See:  VDI  Management 
integers 

See:  parameters 
Intel  80x86, 1-2 
AX  register,  3-3,  3-5 
BX  register,  3-3,  3-5 
DI  register,  1-4,  3-3, 3-5 
ES  register,  1-4, 3-3,  3-5 
offset  address,  3-3 
register  for  command  token,  3-3 
register  for  number  of  parameters,  3-3 
register  for  packet  offset  address,  3-3 
register  for  packet  segment  address,  3-3 
register  for  return  codes,  3-3 
segment  address,  3-3 
interfaces 

See  also:  ASCII  interface 
See  also:  binary  interface 
ASCII  and  binary  compared,  2-3,  3-1 
design  criteria,  2-2-2-3 
reasons  for  two,  2-3 
interoperability 

See:  device  interoperability 
interrupt 

See  also:  software  interrupts 
10H,  7-2,  7-18,  7-22,  7-24,  B-l 
handlers,  4-3— 4-4,  4-10 
vectors,  4-3 
IOCTL,  4-9 
IVDEV,  3-7-3-8 

duplicate  file  name,  3-8 
IVINT,  3-4 

setting,  4-9-4-10 
iwer  parameter 
syGetstate,  6-9 
IWER  signature,  3-4 
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K 

keyboard 

See:  XY-input  device 
keyer 

See:  video  overlay  subsystem 


L 

length  parameter 

vmGetPalette,  7-12-7-13 
vmSetPalette,  7-28 
light  pen 

See:  XY-input  devices 
logcolors  parameter 
default,  7-21 
vmGetState,  7-18 
logical  colors 
See:  colors 

See:  logcolors  parameter 
See:  vmGetPalette 
See:  vmGetState 
See:  vmSetPalette 
logical  device  numbers 
See:  device  numbers 


M 

Macintosh 
See:  Apple 
manufacturer  name 

See:  mfgname  parameter 
manufacturer  version 
See:  mfgver  parameter 
MCGA  standard  modes,  B-l 
mfgname  parameter 
syGetState,  6-9 
mfgver  parameter 
syGetState,  6-9 
microprocessor 
See:  Intel  80x86 
Microsoft  Windows,  2-2 
mode  trapping 

See:  visual  management 
See:  vmlnit 
modes 

See:  graphics  modes 
See:  overlay  modes 
See:  scan-altered  modes 
See:  video  modes 


motion  parameter 
default,  8-12 
vdGetState,  8-8 
mouse 

See:  XY-input  devices 
MS-DOS 
See  also:  BIOS 
See  also:  device  driver 
See  also:  software  interrupts 
file  control  blocks  and  handles,  4-9 
generic  definition,  1-4 
IOCTL  functions,  4-9 
reentrancy,  4-3-4-4 
requiring  specific  versions,  4-3 
tick  routines,  4-3 
version  requirements,  2-2, 4-3 
Multicolor  Graphics  Array 
See:  MCGA 


N 

NTSC 

See  also:  vmode  parameter 

See  also:  vmSetVideo 

active  video,  A-6,  A- 12 

border  widths,  A-7 

EIARS-170A,  A-3 

frames  per  second,  3-2,  8-2 

horizontal  signal  components,  A-5 

horizontal  signal  width,  A-5 

vertical  height.  A- 12 

vertical  timing  components,  A-ll-A-12 


O 

offset  address 
See:  Intel  80x86 
operating  systems 
See  also:  MS-DOS 
supported,  1-2, 2-2, 4-3 
OS/2,  2-2 
overlay  board 

See:  video  overlay  subsystem 
overlay  modes,  7-2-7-3,  B-l 


P 


PAL 

See  also:  vmode  parameter 
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See  also:  vmSetVideo 
active  video,  A-9,  A- 16 
border  widths,  A- 10 
CCIK  470-1,  A-3 
frames  per  second,  3-2,  8-2 
horizontal  signal  components,  A-8 
horizontal  signal  width,  A-8 
vertical  height,  A- 16 
vertical  timing  components,  A- 15 
palette 

See  also:  colors 

See  also:  video  overlay  subsystem 
See  also:  vmGetPalette 
See  also:  vmSetPalette 
memory  allocation,  7-28 
size,  7-4,  7-18 

parameter  packets,  3-4-3-6 
See  also:  parameters 
address  specification,  3-3 
addressing  conventions,  1-4,  3-5 
color  arrays,  4-11—4-12 
contents  after  rounding,  3-6 
contents  passed,  3-4-3-5 
contents  returned,  3-6 
memory  allocation,  3-5 
memory  requirements,  3 -4—3-5 
parameters,  3- 1-3-3 

See  also:  individual  parameter  name  entries 

See  also:  parameter  packets 

ASCII  bit  fields,  4-7 

ASCII  name  summary,  5-5 

ASCD  numbers,  4-7 

ASCII  text,  4-8 

binary  bit  fields,  4-11 

binary  color  arrays,  4-11-4-12,  7-12-7-13 

binary  integers,  4-10 

binary  real  numbers,  4-10 

binary  strings,  4-11 

binary  token  number  summary,  5-5 

core,  2-4-2-5, 5-4-5-5 

extended,  2-4-2-5, 5-4-5-5 

format  of  names,  1-4 

maximum  possible  with  one  command,  3-3 
memory  requirements  for  binary,  3-5 
order,  3-2-3-3 
return  values,  3-6 
rounding,  3-6 
PC  DOS 
See;  MS-DOS 


physcolors  parameter 
default,  7-21 
vmGetState,  7-18 
physical  colors 
See:  colors 

See:  physcolors  parameter 
See:  vmGetState 
See:  vmSetPalette 
platform  independence,  1-1,  2-1 
player 

See:  videodisc  players 
pmsg  parameter 
syErrorMsg,  6-6 
point  mode 

See:  XY-input  devices 
pointer  format 

See:  binary  interface 
portability 

See  also:  compliance  requirements 
CGA  and  EGA  to  VGA  systems,  7-3 
extended  commands,  2-4-2-5 
extended  parameters,  2-4-2-5 
level  addressed,  1-1 
transparent  colors,  7-31 
POSIX,  2-2 
processor 

See:  Intel  80x86 
programming  examples 
BASIC,  C-l-C-2,  C-5 
bit  field  analysis,  C-5 
C,  C-2-C-4 
library  calls,  C-4 
software  interrupt  calls,  C-2-C-3 
psmg  parameter 
vdPassThru,  8-16 

Q 

queue 

See:  syQueue 


R 

r  parameter 

vmGetPalette,  7-12 
vmSetPalette,  7-27 
raw  mode,  4-9 
real  numbers 
See:  parameters 
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recommended  practices 
See  also:  ASCII  interface 
See  also:  binary  interface 
See  also:  compliance  requirements 
See  also:  VDI  Management 
basis,  1-1 
benefits,  1-2 
general  architecture,  2-1 
goals,  1-2 

hardware  requirements,  2-2 
intended  audience,  1-3 
IV  system  level  addressed,  1-1 
language  requirements,  2-2 
operating  systems  addressed,  1-2,  2-2 
portability  level  addressed,  1-1 
processor  architecture  addressed,  1-2 
scope,  1- 1-1-2 
red 

See:  r  parameter 
reentrancy 
See:  MS-DOS 
registers 

See:  Intel  80x86 
registration 

See:  graphics  registration 
remote  control  unit 
See:  remote  parameter 
remote  parameter 
default,  8-12 
vdGetState,  8-8 
vdSet,  8-32 

response  strings,  3-8-3-9,  4-5 
buffering,  4-8 
case,  3-6,  3-9 
delimiters,  3-8, 4-5 
“ERROR  n...”,  3-8 
“OK",  3-8 
syntax,  4-5-4-6 
terminator,  3-8, 4-5 
RGB 

See:  b  parameter 
See:  g  parameter 
See:  r  parameter 
rounding 

color  components,  7-13,  7-27-7-28 
effects  on  parameter  packets,  3-6 
fade  and  dissolve  levels,  7-4-7-5 
times,  7-4-7-5 

videodisc  player  speeds,  8-3 -8-4 


s 

scan 

See:  vdScan 
See:  videodisc  players 
scan-altered  modes,  A-3 
screen  disturbance,  6-14,  7-24-7-25,  7-34,  8-11, 
A- 13 
search 

See:  vdSearch 
See:  videodisc  players 
segment  address 
See:  Intel  80x86 
service  groups,  2-4 
See  also:  commands 

determining  if  present,  4-7,  4-11,  6-9-6-10 
token  values  of  prefixes,  5-1 
software  architecture 

See:  recommended  practices 
software  interrupts 
See  also:  interrupt 
See  also:  IVINT 
21H,  4-4, 4-9 
default,  4-9 

numbers  available,  3-1,  4-9 
programming  example,  C-2-C-3 
user,  4-9 
source  numbers 

See  also:  defsource  parameter 
See  also:  source  parameter 
See  also:  tsources  parameter 
See  also:  vmSetVideo 
default,  7-17 
mapping  to  devices,  7-17 
speed  parameter 
vdGetState,  8-8 
vdPlay,  8-20 
spin  parameter 
default,  8-12 
vdGetState,  8-8 
vdSet,  8-32 
standard 
See:  NTSC 
See:  PAL 
state  parameter 
default,  7-21 
syQueue,  6-15 
vmSetTrans,  7-31 
still  frame 
See:  vdSearch 
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See:  vdStep 
See:  vdStill 
stream  mode 
See:  XY-input  devices 
string 

See:  ASCII  interface 
See:  command  strings 
See:  parameters 
See:  response  strings 
support  parameter 
syGetState,  6-9-6-10 
syCheckError,  6-2-6-5 
syErrorMsg,  6-6-6-7 
syGetState,  6-8-6-11 
sylnit,  6-12-6-18 
sync  signals 

horizontal,  A-2-A-3 
vertical,  A-2-A-3 
system  initialization 
See:  sylnit 
syStop,  6-19-6-20 


T 

tbuttons  parameter 
default,  9-13 
xyGetState,  9-9 
tdevices  parameter 
default,  8-12,  9-13 
vdGetState,  8-8 
xyGetState,  9-9 
tick  chain,  4-3 
time  display 

See:  idxdisplay  parameter 
See:  vdSet 
time  parameter 
vmFade,  7-8 
to  parameter 
vdPlay,  8-21 
token  numbers 

See:  binary  interface 
See:  commands 
See:  parameters 
touch  screen 

See:  XY-input  devices 
transcolors  parameter 
default,  7-21 
vmGetState,  7-18 
transparent  colors 


See:  colors 
tsources  parameter 
vmGetState,  7-18 


u 

UNIX,  2-2 
user  interrupt 

See:  software  interrupts 


V 

vdGetState,  8-5-8-10 
VDI  Management,  2-1 

background  processing,  4-4 

blanking  control,  8-2 

communications,  3-1 

correction  of  XY-input  information,  9-1 

error  buffers,  6-3 

error  handling,  D-l 

genlock  control,  7-3 

graphics  positioning  requirements,  A-l 
installation,  2-4, 4- 1-4-2,  9-2 
interrupt  handle  vector,  4-10 
memory  allocation  for  return  strings,  4-11 
mode  trapping,  7-3 
MS-DOS  calls,  4-3 

nonimmediate  error  detection,  6-2-6-3 
parser  design,  3-3 
rounding,  7-4-7-5,  7-27,  8-3-8-4 
treatment  of  XY-input  information,  9-3 
user  device  numbering,  4-2 
version  number,  3-4 
vdlnit,  8-11-8-14 
vdPassThru,  8-15-8-17 
vdPlay,  8-18-8-23 
vdScan,  8-24-8-26 
vdSearch,  8-27-8-29 
vdSet,  8-30-8-34 
vdStep,  8-35-8-36 
vdStill,  8-37-8-38 
version  number 

See:  iwer  parameter 
See:  IWER  signature 
See:  mfgver  parameter 
See:  VDI  Management 
vertical  blanking 
See:  blanking 
vertical  sync 
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See:  sync  signals 
vertpix  parameter 
default,  7-21 
vmGetState,  7-18 
VGA 

See  also:  emulation  parameter 
See  also:  graphics  adapter 
active  graphics  area,  A-3-A-4 
background  video,  A-3 
blanking  intervals,  A-3 
borders,  A- 13 

emulation  of  CGA/EGA,  7-3-7 -4 
horizontal  registration  in  emulation  mode, 
A-7-A-8,  A-10-A-11 
horizontal  sync,  A-3 
reference  signal,  A-4 
standard  modes,  B-l 

vertical  registration  to  NTSC  video,  A-12-A-15 
vertical  registration  to  PAL  video,  A-16-A-19 
vertical  sync,  A-3 
video  channel 
See:  vdSet 

See:  video  parameter 
Video  Graphics  Array 
See:  VGA 
video  level  control 
See:  vlevel  parameter 
See:  vmFade 
video  modes,  7-3 

See  also:  vmode  parameter 
See  also:  vmSetVideo 
video  overlay  subsystem 

See  also:  individual  vm  command  name  entries 
dissolve  unit,  7-2 
functionality,  7-1-7-2 
keyer,  7-2 
palette,  7-2 
sources,  7-2 
video  parameter 
default,  8-12 
vdGetState,  8-9 
vdSet,  8-33 

video  position  relative  to  graphics 
See:  graphics  registration 
video  standard 
See:  NTSC 
See:  PAL 

videodisc  player  door  control 
See:  door  parameter 


videodisc  player  initialization 
See:  vdlnit 
videodisc  players 

See  also:  individual  vd  command  name  entries 
See  also:  videodiscs 
instant  jump,  8-2 
numbering,  4-2 
Pioneer  4200,  8-3 
play  speeds,  8-2 
scan  speeds,  8-2 
search,  8-2 
Sony  2000,  8-3 
speeds,  8-3-8-4 
videodiscs 

See  also:  disctype  parameter 
See  also:  videodisc  players 
CAV,  8- 1-8-3 
chapters,  8-2 
CLV,  8- 1-8-4 
fields,  8-2 
frames,  8-2 
reference  frame,  A-l 
Virtual  Device  Interface 
See:  VDI  Management 
visual  management 

See  also:  graphics  registration 
See  also:  individual  vm  command  name  entries 
See  also:  video  overlay  subsystem 
genlock  control,  7-3 
graphics  registration,  7-3 
logical  and  physical  colors,  7-4 
mode  trapping,  7-3 
overlay  modes,  7-2-7 -3 
rounding  fade  and  dissolve  levels,  7~4-7-5 
visual  management  initialization 
See:  vmlnit 
vlevel  parameter 
default,  7-21 
vmFade,  7-8 
vmGetState,  7-17 
vmFade,  7-6-7-10 
vmGetPalette,  7-11-7-14 
vmGetState,  7-15-7-20 
vmlnit,  7-21-7-22 
vmode  parameter 
default,  7-21 
vmGetState,  7-18 
vmSetVideo,  7-33-7-34 
VMS,  2-2 
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vmSetGraphics,  7-23-7-25 
vmSetPalette,  7-2S-7-29 
vmSetTrans,  7-30-7-32 
vmSetVideo,  7-33-7-34 


w 

wait  parameter 

effects  on  vdPlay,  8-21 
vdPlay,  8-21-8-22 
vdScan,  8-25 
vdSearch,  8-28 
vdSet,  8-33 
vmFade,  7-8 
width  parameter 
default,  7-21 
vmGetState,  7-18 
vmSetGraphics,  7-24 
Windows 

See:  Microsoft  Windows 


X 

max  parameter 
default,  9-13 
xyGetState,  9-9 
xySet,  9-17 
xmaxdip  parameter 
default,  9-13 
xyGetState,  9-10 
xySet,  9-17 
xmin  parameter 
default,  9-13 
xyGetState,  9-9 
xySet,  9-17 
xminclip  parameter 
default,  9-13 
xyGetState,  9-10 
xySet,  9-17 
xoffset  parameter 
default,  7-21 
vmGetState,  7-19 
vmSetGraphics,  7-24 
xpos  parameter 
default,  9-13 
xyGetlnput,  9-5 
xySet,  9-17 

XY-coordinate  space,  9-2-9-3 
See  also:  xyGetState 


See  also:  xySet 

correcting  for  multiple  physical  devices,  9-1 
XY-input  device  initialization 
See:  xylnit 
XY-input  devices 

See  also:  individual  xy  command  name  entries 

buttons,  9-3 

calibration,  9-3 

cursor  keypad,  9-2 

cursor  management,  9-2 

graphics  plane  management,  9-2 

keyboard,  9-2 

mapping,  9- 1-9-2 

multiple  physical  to  single  logical,  9- 1-9-2 
numbering,  4-2 
point  mode,  9-3 
requirements,  2-2 
stream  mode,  9-3 
xyGetlnput,  9-4-9-6 
xyGetState,  9-7-9-11 
xylnit,  9-12-9-14 
xySet,  9-15-9-18 


Y 

ymax  parameter 
default,  9-13 
xyGetState,  9-9 
xySet,  9-17 
ymaxclip  parameter 
default,  9-13 
xyGetState,  9-10 
xySet,  9-17 
ymin  parameter 
default,  9-13 
xyGetState,  9-9 
xySet,  9-17 
ymindip  parameter 
default,  9-13 
xyGetState,  9-10 
xySet,  9-17 
yoffset  parameter 
default,  7-21 
vmGetState,  7-19 
vmSetGraphics,  7-24 
ypos  parameter 
default,  9-13 
xyGetlnput,  9-5 
xySet,  9-17 
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